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 Desktop
Cursor
Windsurf
claude mcp add superdoc -- npx @superdoc-dev/mcp
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:{
"mcpServers": {
"superdoc": {
"command": "npx",
"args": ["@superdoc-dev/mcp"]
}
}
}
Add to ~/.cursor/mcp.json:{
"mcpServers": {
"superdoc": {
"command": "npx",
"args": ["@superdoc-dev/mcp"]
}
}
}
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
superdoc_open loads a .docx file and returns a session_idsuperdoc_find locates content and returns target addresses- Edit tools (
superdoc_insert, superdoc_replace, superdoc_delete, superdoc_format) use those addresses
superdoc_save writes changes to disksuperdoc_close releases the session
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 |
| 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 |
| 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
Debugging
Test the server directly with the MCP Inspector:
npx @modelcontextprotocol/inspector -- npx @superdoc-dev/mcp
- 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
