The docx-mcp server enables reading, editing, and validating Microsoft Word (.docx) documents via OOXML-level manipulation, with advanced support for track changes, comments, and footnotes.
Document Management
Open, close, save, and retrieve overview stats (paragraph count, headings, footnotes, comments, images) for .docx files
Reading & Searching
Extract the heading structure (levels, text, styles, paraIds)
Retrieve specific paragraphs by
paraIdSearch across body, footnotes, and comments using plain text or regex
Track Changes
Insert text with
w:insmarkup (appears as green underlined text in Word)Delete text with
w:delmarkup (appears as red strikethrough in Word)
Comments
List all comments (ID, author, date, text)
Add comments anchored to specific paragraphs
Reply to existing comments to create threaded conversations
Footnotes
List all footnotes with ID and content
Add footnotes with superscript references to specific paragraphs
Validate cross-references between the document body and
footnotes.xml
Validation & Auditing
Validate
paraIduniqueness across all document parts (body, footnotes, headers, footers, comments)Remove VML watermarks (e.g., DRAFT) from document headers
Run comprehensive structural audits covering footnotes, paraIds, heading continuity, bookmark pairing, relationship targets, image references, and residual artifacts
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@docx-mcpChange 'Net 30' to 'Net 60' in invoice.docx using track changes."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
docx-mcp
MCP server for reading and editing Word (.docx) documents with track changes, comments, footnotes, and structural validation.
The only cross-platform MCP server that combines track changes, comments, and footnotes in a single package — with OOXML-level structural validation that no other server offers.
Features
Capability | Description |
Track changes | Insert/delete text with proper |
Comments | Add comments, reply to threads, read existing comments |
Footnotes | Add footnotes, list all footnotes, validate cross-references |
ParaId validation | Check uniqueness across all document parts (headers, footers, footnotes) |
Watermark removal | Detect and remove VML watermarks (e.g., DRAFT) from headers |
Structural audit | Validate footnotes, paraIds, heading levels, bookmarks, relationships, images |
Text search | Search across body, footnotes, and comments — plain text or regex |
Heading extraction | Get the full heading structure with levels and paragraph IDs |
Installation
# Claude Code (recommended)
claude mcp add docx-mcp -- uvx docx-mcp-server
# With pip
pip install docx-mcp-server
# With uvx
uvx docx-mcp-serverOptional: Install the companion skill for Claude Code — it teaches Claude when and how to use the tools automatically:
curl -sSL https://raw.githubusercontent.com/SecurityRonin/docx-mcp/main/install.sh | bash
Configuration
Claude Desktop / Claude Code
Add to your MCP settings:
{
"mcpServers": {
"docx-mcp": {
"command": "uvx",
"args": ["docx-mcp-server"]
}
}
}Cursor / Windsurf / VS Code
Add to your MCP configuration file:
{
"mcpServers": {
"docx-mcp": {
"command": "uvx",
"args": ["docx-mcp-server"]
}
}
}With pip install
{
"mcpServers": {
"docx-mcp": {
"command": "docx-mcp"
}
}
}Available Tools
Document Lifecycle
Tool | Description |
| Open a .docx file for reading and editing |
| Close the current document and clean up |
| Get overview stats (paragraphs, headings, footnotes, comments) |
| Save changes back to .docx (can overwrite or save to new path) |
Reading
Tool | Description |
| Get heading structure with levels, text, styles, and paraIds |
| Search across body, footnotes, and comments (text or regex) |
| Get full text and style of a paragraph by paraId |
Track Changes
Tool | Description |
| Insert text with tracked-change markup ( |
| Mark text as deleted with tracked-change markup ( |
Comments
Tool | Description |
| List all comments with ID, author, date, and text |
| Add a comment anchored to a paragraph |
| Reply to an existing comment (threaded) |
Footnotes
Tool | Description |
| List all footnotes with ID and text |
| Add a footnote with superscript reference |
| Cross-reference IDs between document body and footnotes.xml |
Validation & Audit
Tool | Description |
| Check paraId uniqueness and range validity across all parts |
| Remove VML watermarks from document headers |
| Comprehensive structural audit (footnotes, paraIds, headings, bookmarks, relationships, images, artifacts) |
Example Workflow
1. open_document("/path/to/contract.docx")
2. get_headings() → see document structure
3. search_text("30 days") → find the clause
4. delete_text(para_id, "30 days") → tracked deletion
5. insert_text(para_id, "60 days") → tracked insertion
6. add_comment(para_id, "Extended per client request")
7. audit_document() → verify structural integrity
8. save_document("/path/to/contract_revised.docx")The resulting document opens in Microsoft Word with proper revision marks — deletions shown as red strikethrough, insertions as green underline, comments in the sidebar.
How It Works
A .docx file is a ZIP archive of XML files. This server:
Unpacks the archive to a temporary directory
Parses all XML parts with lxml and caches them in memory
Edits the cached DOM trees directly (no intermediate abstraction layer)
Repacks modified XML back into a valid .docx archive
This approach gives full control over OOXML markup — essential for track changes (w:ins/w:del), comments (w:comment + range markers), and structural validation that higher-level libraries like python-docx don't expose.
Requirements
Python 3.10+
lxml
License
MIT