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 through the Model Context Protocol — the open standard for connecting AI tools to agents.

The MCP server is in alpha. Tools and output formats may change.

Setup

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

Claude Code

claude mcp add superdoc -- npx @superdoc-dev/mcp

Claude Desktop

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

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

Cursor

Add to ~/.cursor/mcp.json:

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

Windsurf

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

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

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:

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

• LLM Tools — build custom LLM integrations with the SDK
• CLI — edit documents from the terminal
• SDKs — typed Node.js and Python wrappers
• Document API — the in-browser API that defines the operation set
• AI Agents — headless mode for server-side AI workflows