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 w:ins/w:del markup — shows as revisions in Word |
| 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
# With pip
pip install docx-mcp
# With uvx (recommended for MCP)
uvx docx-mcp
Configuration
Claude Desktop / Claude Code
Add to your MCP settings:
{
"mcpServers": {
"docx-mcp": {
"command": "uvx",
"args": ["docx-mcp"]
}
}
}
Cursor / Windsurf / VS Code
Add to your MCP configuration file:
{
"mcpServers": {
"docx-mcp": {
"command": "uvx",
"args": ["docx-mcp"]
}
}
}
With pip install
{
"mcpServers": {
"docx-mcp": {
"command": "docx-mcp"
}
}
}
Available Tools
Document Lifecycle
| Tool | Description |
|---|---|
open_document | Open a .docx file for reading and editing |
close_document | Close the current document and clean up |
get_document_info | Get overview stats (paragraphs, headings, footnotes, comments) |
save_document | Save changes back to .docx (can overwrite or save to new path) |
Reading
| Tool | Description |
|---|---|
get_headings | Get heading structure with levels, text, styles, and paraIds |
search_text | Search across body, footnotes, and comments (text or regex) |
get_paragraph | Get full text and style of a paragraph by paraId |
Track Changes
| Tool | Description |
|---|---|
insert_text | Insert text with tracked-change markup (w:ins) |
delete_text | Mark text as deleted with tracked-change markup (w:del) |
Comments
| Tool | Description |
|---|---|
get_comments | List all comments with ID, author, date, and text |
add_comment | Add a comment anchored to a paragraph |
reply_to_comment | Reply to an existing comment (threaded) |
Footnotes
| Tool | Description |
|---|---|
get_footnotes | List all footnotes with ID and text |
add_footnote | Add a footnote with superscript reference |
validate_footnotes | Cross-reference IDs between document body and footnotes.xml |
Validation & Audit
| Tool | Description |
|---|---|
validate_paraids | Check paraId uniqueness and range validity across all parts |
remove_watermark | Remove VML watermarks from document headers |
audit_document | 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