README.md
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
# Claude Code (recommended)
claude mcp add docx-mcp -- uvx docx-mcp-server
# With pip
pip install docx-mcp-server
# With uvx
uvx docx-mcp-server
Optional: 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_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 inserti
Tools 18
open_documentOpen a .docx file for reading and editingclose_documentClose the current document and clean upget_document_infoGet overview stats (paragraphs, headings, footnotes, comments)save_documentSave changes back to .docxget_headingsGet heading structure with levels, text, styles, and paraIdssearch_textSearch across body, footnotes, and commentsget_paragraphGet full text and style of a paragraph by paraIdinsert_textInsert text with tracked-change markupdelete_textMark text as deleted with tracked-change markupget_commentsList all comments with ID, author, date, and textadd_commentAdd a comment anchored to a paragraphreply_to_commentReply to an existing commentget_footnotesList all footnotes with ID and textadd_footnoteAdd a footnote with superscript referencevalidate_footnotesCross-reference IDs between document body and footnotes.xmlvalidate_paraidsCheck paraId uniqueness and range validityremove_watermarkRemove VML watermarks from document headersaudit_documentComprehensive structural audit of the documentTry it
→Open the contract.docx file and list all the headings to understand the document structure.
→Search for the term 'liability' in the document and tell me which paragraphs it appears in.
→Add a comment to the paragraph with paraId 123 asking for clarification on the terms.
→Perform a structural audit on this document to ensure all footnotes and paraIds are valid.
→Delete the sentence 'The service fee is $100' and insert 'The service fee is $150' using tracked changes.