Docx Redline MCP
An MCP server for inspecting and editing Microsoft .docx files with support for real tracked changes and comments.
Ask AI about Docx Redline MCP
Powered by Claude · Grounded in docs
I know everything about Docx Redline MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
DOCX Redline MCP
Local stdio MCP server for inspecting and editing Microsoft .docx files through OOXML package parts.
It is intended for agent workflows that need to:
- open a local
.docx - inspect OOXML parts such as
word/document.xml - apply real Word tracked changes through
@ansonlai/docx-redline-js - add comments and maintenance operations safely
- save back in place or to a new output path
Status
Current behavior is hardened around the failure modes discovered during end-to-end Word testing:
- MCP logging is routed to
stderrso stdio transport is not corrupted - package updates are validated before the in-memory session is committed
- invalid comment/revision combinations are rejected and rolled back
delete_all_commentsclears both inline anchors andword/comments.xml- redline operations normalize hidden field scaffolding (
w:fldChar,w:instrText) and proofing markers (w:proofErr) in the matched target paragraph before diffing - batch redline application is supported through
apply_operations
Requirements
- Node.js 18 or newer
Install
npm install
Run
node src/index.js
Package binary:
npx docx-redline-mcp
MCP Tools
open_docx
Open a .docx file and create a working handle.
{
"path": "C:/contracts/master-services-agreement.docx"
}
list_parts
List package parts for an open handle.
{
"handle": "doc_..."
}
read_part
Read an OOXML part as XML text or get a binary summary.
{
"handle": "doc_...",
"partPath": "word/document.xml",
"maxChars": 12000
}
Binary export:
{
"handle": "doc_...",
"partPath": "word/media/image1.png",
"includeBase64": true
}
write_part
Replace a writable XML part in memory.
{
"handle": "doc_...",
"partPath": "word/document.xml",
"xml": "<w:document>...</w:document>"
}
Writable XML parts:
word/document.xmlword/comments.xmlword/numbering.xmlword/header*.xmlword/footer*.xml[Content_Types].xml
apply_operation
Apply one structured operation to word/document.xml.
Redline example:
{
"handle": "doc_...",
"author": "Roo",
"operation": {
"type": "redline",
"target": "Original text",
"modified": "Updated text"
}
}
Comment example:
{
"handle": "doc_...",
"author": "Roo",
"operation": {
"type": "comment",
"target": "Original paragraph text",
"textToComment": "Original",
"commentContent": "Explain the change"
}
}
Maintenance operations:
accept_all_tracked_changesreject_all_tracked_changesdelete_all_comments
apply_operations
Apply multiple structured operations in a single batch. This is the preferred path when one edit session needs several redlines/comments against the same open document.
{
"handle": "doc_...",
"author": "Roo",
"operations": [
{
"type": "redline",
"target": "Original text",
"modified": "Updated text"
},
{
"type": "comment",
"target": "Other paragraph",
"textToComment": "Other",
"commentContent": "Reasoning"
}
]
}
save_docx
Save the working package.
In place:
{
"handle": "doc_..."
}
To a separate file:
{
"handle": "doc_...",
"outputPath": "C:/contracts/master-services-agreement-copy.docx"
}
Behavior Notes
- Each
open_docxcall creates an in-memory working session. save_docxwrites back to the original file unlessoutputPathis supplied.- Non-XML parts are read-only.
write_partvalidates XML before accepting it.apply_operationandapply_operationsvalidate the resulting package before updating the session state.- On failure, the server rolls back the affected
word/document.xmlandword/comments.xmlstate. - For redlines, the server preserves visible Word cross-reference output such as
9.1or10.6but removes hidden field instruction scaffolding before diffing. - Comment anchors that cross tracked insertion/deletion boundaries are rejected because Word commonly refuses to open those packages.
Logging
- Default MCP log level is
warn - Logs are written to
stderr, notstdout - To enable engine diagnostics safely:
$env:DOCX_REDLINE_MCP_LOG_LEVEL = "info"
node src/index.js
Troubleshooting
Transport closedduring a tool call:- check for any dependency or local logging writing to
stdout
- check for any dependency or local logging writing to
- Word rejects the saved file even though XML looks valid:
- inspect the revised paragraph for hidden field runs (
w:fldChar,w:instrText) or proofing markers (w:proofErr) - prefer the server redline path over direct XML surgery so the normalization step runs
- inspect the revised paragraph for hidden field runs (
- Comment operation rejected because of a tracked-change boundary:
- re-anchor the comment to stable text outside the revised span
Test
npm test
The test suite covers:
- basic tool handler behavior
- package read/write/save
- rollback on invalid comment/revision markup
- batch operation handling
- real-DOCX diagnostic generation
- field/proofing normalization regressions
License
MIT. See LICENSE.
