> ## Documentation Index
> Fetch the complete documentation index at: https://superdoc-nick-sd-2099-images-core-lifecycle-placement-seman.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Give AI agents direct access to .docx files through the Model Context Protocol

The SuperDoc MCP server lets AI agents open, read, edit, and save `.docx` files. It exposes the same operations as the [Document API](/document-api/overview) through the [Model Context Protocol](https://modelcontextprotocol.io) — the open standard for connecting AI tools to agents.

<Info>
  The MCP server is in <strong>alpha</strong>. Tools and output formats may change.
</Info>

## Setup

Install once. Your MCP client spawns the server automatically on each conversation.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add superdoc -- npx @superdoc-dev/mcp
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "superdoc": {
          "command": "npx",
          "args": ["@superdoc-dev/mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "superdoc": {
          "command": "npx",
          "args": ["@superdoc-dev/mcp"]
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "superdoc": {
          "command": "npx",
          "args": ["@superdoc-dev/mcp"]
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Workflow

Every interaction follows the same pattern: open, read or edit, save, close.

```
superdoc_open → superdoc_find / superdoc_get_text → edit tools → superdoc_save → superdoc_close
```

1. `superdoc_open` loads a `.docx` file and returns a `session_id`
2. `superdoc_find` locates content and returns target addresses
3. Edit tools (`superdoc_insert`, `superdoc_replace`, `superdoc_delete`, `superdoc_format`) use those addresses
4. `superdoc_save` writes changes to disk
5. `superdoc_close` releases the session

## Tools

23 tools in eight groups. All tools take a `session_id` from `superdoc_open`.

### Lifecycle

| Tool             | Input                | Description                                             |
| ---------------- | -------------------- | ------------------------------------------------------- |
| `superdoc_open`  | `path`               | Open a `.docx` file. Returns `session_id` and file path |
| `superdoc_save`  | `session_id`, `out?` | Save to the original path, or to `out` if specified     |
| `superdoc_close` | `session_id`         | Close the session. Unsaved changes are lost             |

### Query

| Tool                | Input                                                  | Description                                                                |
| ------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------- |
| `superdoc_find`     | `session_id`, `type?`, `pattern?`, `limit?`, `offset?` | Search by node type, text pattern, or both. Returns matches with addresses |
| `superdoc_get_node` | `session_id`, `address`                                | Get details about a specific node by its address                           |
| `superdoc_info`     | `session_id`                                           | Document metadata: structure summary, node counts, capabilities            |
| `superdoc_get_text` | `session_id`                                           | Full plain-text content of the document                                    |

### Mutation

All mutation tools accept `suggest?` — set to `true` to make the edit a tracked change instead of a direct edit.

| Tool               | Input                                      | Description                       |
| ------------------ | ------------------------------------------ | --------------------------------- |
| `superdoc_insert`  | `session_id`, `text`, `target`, `suggest?` | Insert text at a target position  |
| `superdoc_replace` | `session_id`, `text`, `target`, `suggest?` | Replace content at a target range |
| `superdoc_delete`  | `session_id`, `target`, `suggest?`         | Delete content at a target range  |

### Format

| Tool              | Input                                       | Description                                                                               |
| ----------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `superdoc_format` | `session_id`, `style`, `target`, `suggest?` | Toggle formatting on a text range. Styles: `bold`, `italic`, `underline`, `strikethrough` |

### Create

| Tool              | Input                                                      | Description                                                                          |
| ----------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `superdoc_create` | `session_id`, `type`, `text?`, `level?`, `at?`, `suggest?` | Create a block element. Types: `paragraph`, `heading` (headings require `level` 1-6) |

### Track changes

Review and resolve tracked changes (suggestions) in the document.

| Tool                          | Input                                      | Description                                               |
| ----------------------------- | ------------------------------------------ | --------------------------------------------------------- |
| `superdoc_list_changes`       | `session_id`, `type?`, `limit?`, `offset?` | List tracked changes with type, author, date, and excerpt |
| `superdoc_accept_change`      | `session_id`, `id`                         | Accept a single change, applying it to the document       |
| `superdoc_reject_change`      | `session_id`, `id`                         | Reject a single change, reverting it                      |
| `superdoc_accept_all_changes` | `session_id`                               | Accept all tracked changes at once                        |
| `superdoc_reject_all_changes` | `session_id`                               | Reject all tracked changes at once                        |

### Comments

Add and manage comments anchored to text ranges.

| Tool                       | Input                              | Description                                              |
| -------------------------- | ---------------------------------- | -------------------------------------------------------- |
| `superdoc_add_comment`     | `session_id`, `text`, `target`     | Add a comment anchored to a text range                   |
| `superdoc_list_comments`   | `session_id`, `include_resolved?`  | List all comments with author, status, and anchored text |
| `superdoc_reply_comment`   | `session_id`, `comment_id`, `text` | Reply to an existing comment thread                      |
| `superdoc_resolve_comment` | `session_id`, `comment_id`         | Mark a comment as resolved                               |

### Lists

| Tool                     | Input                                       | Description                                             |
| ------------------------ | ------------------------------------------- | ------------------------------------------------------- |
| `superdoc_insert_list`   | `session_id`, `target`, `position`, `text?` | Insert a list item before or after an existing one      |
| `superdoc_list_set_type` | `session_id`, `target`, `kind`              | Change a list between `ordered` (numbered) and `bullet` |

## Suggesting mode

Set `suggest=true` on any mutation, format, or create tool to make edits appear as tracked changes. The document stays unchanged until someone accepts the suggestions — in Word, in SuperDoc's browser editor, or programmatically via the track changes tools.

## How it works

The MCP server runs as a local subprocess, communicating over stdio. It manages document sessions in memory — each `superdoc_open` creates an Editor instance, and all subsequent operations run against that in-memory state until you `superdoc_save`.

```
AI Agent (Claude, Cursor, Windsurf)
  │ MCP protocol (stdio)
  ▼
@superdoc-dev/mcp
  │ Document API
  ▼
SuperDoc Editor (in-memory)
  │ export
  ▼
.docx file on disk
```

Your documents never leave your machine. The server runs locally, reads files from disk, and writes back to disk.

## Debugging

Test the server directly with the MCP Inspector:

```bash theme={null}
npx @modelcontextprotocol/inspector -- npx @superdoc-dev/mcp
```

This opens a browser UI where you can call each tool manually and inspect the raw JSON-RPC messages.

## Related

* [CLI](/document-engine/cli) — edit documents from the terminal
* [SDKs](/document-engine/sdks) — typed Node.js and Python wrappers
* [Document API](/document-api/overview) — the in-browser API that defines the operation set
* [AI Agents](/getting-started/ai-agents) — headless mode for server-side AI workflows