@superdoc/mcp

MCP server for SuperDoc. Lets AI agents open, read, edit, and save .docx files through the Model Context Protocol.

Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Quick start

npx @superdoc/mcp

The server runs locally over stdio as a subprocess. You don't run it directly; your MCP client spawns it.

Setup

Claude Code

claude mcp add superdoc -- npx @superdoc/mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "superdoc": {
      "command": "npx",
      "args": ["@superdoc/mcp"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "superdoc": {
      "command": "npx",
      "args": ["@superdoc/mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "superdoc": {
      "command": "npx",
      "args": ["@superdoc/mcp"]
    }
  }
}

Tools

Three lifecycle tools are always registered. The editing surface depends on MCP_PRESET:

| MCP_PRESET | Tools | | --- | --- | | legacy (default) | 13: 3 lifecycle + 10 grouped intent tools | | core | 5: 3 lifecycle + superdoc_inspect and superdoc_perform_action |

All tools except superdoc_open take a session_id from superdoc_open.

Pass absolute paths. A relative path resolves against the server process's working directory, which your MCP client chooses. superdoc_open also opens a blank document when the path does not exist rather than reporting an error, so a wrong path presents as an empty file instead of a failure.

The server reads and writes any path it is given, with no restriction to a particular directory. Run it under a container, a dedicated user account, or an OS sandbox if you need to bound what it can reach.

superdoc_save has no overwrite guard: it resolves out and writes it, replacing any file already there, including the source. Point the agent at copies, and preflight the destination yourself when a workflow cannot tolerate that.

Lifecycle

| Tool | Description | | --- | --- | | superdoc_open | Open a .docx file by absolute path and get a session_id. A missing path opens a blank document | | superdoc_save | Save the document to disk (original path or custom out path). Overwrites an existing file without warning | | superdoc_close | Close the session and release memory |

Intent tools (legacy preset)

Most intent tools take an action argument selecting the operation within the group. superdoc_search is the exception: it takes select, not action.

| Tool | Covers | | --- | --- | | superdoc_get_content | Read the document as text, markdown, HTML, blocks, or metadata | | superdoc_search | Find content and return stable targets. Takes select, not action | | superdoc_edit | Insert, replace, and delete text, plus undo and redo | | superdoc_format | Inline and paragraph formatting, styles, direction, and flow | | superdoc_create | Create paragraphs, headings, and tables | | superdoc_list | Create, convert, nest, split, merge, and renumber lists | | superdoc_table | Table structure, content, and styling | | superdoc_comment | Create, update, resolve, and read comment threads | | superdoc_track_changes | List tracked changes and decide on them | | superdoc_mutations | Preview and apply multi-step edits as one atomic batch |

Each tool's exact action list is generated from the Document API contract and changes with it. Read the advertised schema rather than a copy of it. Every tool's JSON Schema is served over MCP, and getToolCatalog('legacy') in @superdoc/sdk returns the same data.

Workflow

Every interaction follows the same pattern:

open → read/search → edit → save → close

1. superdoc_open loads a document and returns a session_id
2. superdoc_get_content reads the current document and superdoc_search finds stable handles or addresses
3. Intent tools use session_id plus action to modify content
4. superdoc_save writes changes to disk
5. superdoc_close releases the session

Steps 2 and 3 name legacy tools. Under MCP_PRESET=core the shape is the same, but reads go through superdoc_inspect and edits through superdoc_perform_action. The lifecycle steps are identical under both presets.

Tracked changes

Actions that support tracked edits use the underlying Document API's changeMode: "tracked" option.

Reviewing them differs by preset. Under legacy, call superdoc_track_changes. Under core that tool does not exist: use superdoc_perform_action with accept_tracked_changes or reject_tracked_changes.

Not every action honors changeMode. Some ignore it and edit directly, and move_range accepts it and then fails without mutating, so check the action rather than assuming the argument applied.

Every session authors its changes as MCP Server; there is no way to configure that identity. Two MCP deployments editing the same document produce tracked changes a reviewer cannot tell apart. Use the SDK when attribution matters.

Development

# Run locally
bun run src/index.ts

# Run tests
bun test

# Test with MCP Inspector
npx @modelcontextprotocol/inspector -- bun run src/index.ts

License

See the SuperDoc license.