@knorq/docx-mcp-server
Advanced tools
MCP server for DOCX document editing — read, edit, format, comment, highlight, and track changes in Word documents
A local MCP server for reading and editing Word (.docx) documents. Works with Claude Code, Cursor, and any MCP-compatible client.
33 tools for document content, formatting, comments, page layout, and track changes — all running locally via stdio with no file uploads.
| Category | Tools |
|---|---|
| Read | read_document, get_document_info, search_text, list_images |
| Edit | replace_texts, edit_paragraphs, insert_paragraphs, delete_paragraphs |
| Format | format_text, set_paragraph_formats, highlight_text, set_headings |
| Structure | insert_table, create_document, apply_document_preset |
| Review | add_comment, add_comments, read_comments, reply_to_comment, delete_comment |
| Track changes | accept_all_changes, reject_all_changes |
| Page layout | get_page_layout, set_page_layout |
| Headers/footers | read_header_footer |
| Tables | edit_table_cells |
| Footnotes | read_footnotes |
The editing tools (replace_texts, edit_paragraphs, insert_paragraphs, delete_paragraphs) support tracked changes — edits are recorded as Word revisions (w:ins/w:del) with author and timestamp, so reviewers can accept or reject them in Word.
Track changes is on by default. Pass track_changes: false to make direct edits.
Use read_document with show_revisions: true to see tracked changes annotated as [-deleted-] and [+inserted+]. The default view shows accepted text only.
Use accept_all_changes / reject_all_changes to finalize or revert all pending revisions.
get_page_layout / set_page_layout support:
npm install -g @knorq/docx-mcp-server
Then add to your MCP config (see Configuration below).
Just add the config — npx downloads and runs it automatically:
{
"mcpServers": {
"docx-editor": {
"command": "npx",
"args": ["-y", "@knorq/docx-mcp-server"]
}
}
}
git clone https://github.com/knorq-ai/docx-mcp-server.git
cd docx-mcp-server
npm install
npm run build
npm link # makes `docx-mcp-server` available globally
Add to your project's .mcp.json (per-project) or ~/.claude/settings.json (global):
{
"mcpServers": {
"docx-editor": {
"command": "npx",
"args": ["-y", "@knorq/docx-mcp-server"]
}
}
}
Add to your MCP server configuration in Cursor settings:
{
"mcpServers": {
"docx-editor": {
"command": "npx",
"args": ["-y", "@knorq/docx-mcp-server"]
}
}
}
If you built from source and ran npm link:
{
"mcpServers": {
"docx-editor": {
"command": "docx-mcp-server"
}
}
}
Or reference the built file directly:
{
"mcpServers": {
"docx-editor": {
"command": "node",
"args": ["/absolute/path/to/docx-mcp-server/dist/index.js"]
}
}
}
npm publish
Recipients install with:
npm install -g @knorq/docx-mcp-server
Or skip the install entirely — just share the .mcp.json config with the npx setup above and it works out of the box.
Share the repository. Recipients run:
git clone https://github.com/knorq-ai/docx-mcp-server.git
cd docx-mcp-server
npm install
npm run build
npm link
Then add the config above.
read_document — Read content with block indices, styles, and formatting hints. Use show_revisions to see tracked changes.
file_path, start_paragraph?, end_paragraph?, show_revisions?
get_document_info — Paragraph count, heading outline, table count, comment status.
file_path
search_text — Search with context snippets.
file_path, query, case_sensitive?
list_images — List all embedded images with filenames, dimensions, alt text, and block indices.
file_path
All editing tools accept track_changes (default true) and author (default "Claude").
replace_texts — Apply one or more find/replace operations in a single open/save cycle. Handles text spanning multiple runs.
track_changes: false, items are applied sequentially: a later item can match text produced by an earlier item.track_changes: true (default), the engine rejects overlapping items where item N's search shares text with any earlier item M's replace (in either direction). Tracked sequential replacement cannot safely chain overlapping items — nested w:ins/w:del does not round-trip through reject_all_changes. Workaround: issue separate replace_texts calls (one per item) or use track_changes: false with allow_untracked_edit: true.file_path, items (array of {search, replace, case_sensitive?}), track_changes?, author?, include_headers_footers?
edit_paragraphs — Replace the text content of one or more paragraphs in a single open/save cycle.
file_path, edits (array of {paragraph_index, new_text}), track_changes?, author?
insert_paragraphs — Insert one or more paragraphs in one operation. Handles index shifting internally.
file_path, paragraphs (array of {text, position, style?, num_id?, num_level?, copy_format_from?}), track_changes?, author?
delete_paragraphs — Delete one or more paragraphs in one operation. Handles index reordering internally.
file_path, paragraph_indices, track_changes?, author?
format_text — Apply bold, italic, underline, font, size, color, highlight to matching text.
file_path, search, bold?, italic?, underline?, strikethrough?, highlight_color?, font_name?, font_size?, font_color?, case_sensitive?
set_paragraph_formats — Apply alignment, spacing, indentation to one or more paragraphs in one operation. Each group bundles a list of paragraph indices with the formatting to apply to them.
file_path, groups (array of {indices, alignment?, space_before?, space_after?, line_spacing?, indent_left?, indent_right?, first_line_indent?, hanging_indent?})
highlight_text — Highlight matching text with a color.
file_path, search, color?, case_sensitive?
set_headings — Convert one or more paragraphs to headings (level 1-9) in one operation.
file_path, headings (array of {paragraph_index, level})
insert_table — Insert a table with optional cell data.
file_path, position, rows, cols, data?
create_document — Create a new .docx file with optional title, content, and style preset.
file_path, title?, content?, preset?
By default create_document keeps the generated document generic. If you want a Japanese business-document starting point, pass preset: "ja-business" to seed styles.xml with Yu Gothic body text, 11pt sizing, roomier paragraph spacing, and less cramped heading spacing.
apply_document_preset — Apply a document-wide style preset in one pass by updating styles.xml.
file_path, preset
Use this when you want to restyle an existing document without repeated format_text calls per paragraph. The preset rewrites docDefaults and the Heading 1–Heading 3 styles; an existing Normal style and other custom styles are preserved.
add_comment — Anchor a comment to specific text.
file_path, anchor_text, comment_text, author?
add_comments — Add multiple comments in one operation. Supports partial success.
file_path, comments (array of {anchor_text, comment_text, author?}), default_author?
read_comments — List all comments with IDs, authors, text, and threaded replies.
file_path
reply_to_comment — Reply to an existing comment, creating a threaded conversation.
file_path, parent_comment_id, comment_text, author?
delete_comment — Remove a comment by ID.
file_path, comment_id
accept_all_changes — Accept all tracked changes. Insertions become permanent, deletions are removed.
file_path
reject_all_changes — Reject all tracked changes. Insertions are removed, deleted text is restored.
file_path
get_page_layout — Read page size, margins, orientation.
file_path
set_page_layout — Set page size, margins, orientation by preset or custom mm values.
file_path, page_size_preset?, orientation?, width_mm?, height_mm?, margin_preset?, top_mm?, right_mm?, bottom_mm?, left_mm?, header_mm?, footer_mm?, gutter_mm?
read_header_footer — Read the text content of all headers and footers.
file_path
edit_table_cells — Replace the text content of one or more table cells in a single open/save cycle. Cells can span different tables.
file_path, edits (array of {block_index, row_index, col_index, new_text}), track_changes?, author?
read_footnotes — Read all footnotes with their IDs and text content.
file_path
AI agents can manipulate DOCX via raw Python (python-docx), but MCP tools are significantly more token-efficient:
| Metric | MCP tools | Raw Python |
|---|---|---|
| Output tokens per operation | 65–95% less | Baseline (agent must generate full code) |
| Cost per operation | 55–90% less | Baseline |
| Break-even | 3–5 operations | — |
| Debug iterations | None (validated inputs) | ~1.5 retries/task on average |
| Task | MCP | Python (python-docx) | Savings |
|---|---|---|---|
| Read paragraphs 0–20 | ~18 | ~52 (open, iterate, print) | 65% |
| Search and replace text | ~16 | ~67 (iterate paragraphs, run traversal) | 76% |
| Add tracked change (insert) | ~32 | ~326 (build w:ins/w:del XML, datetime, author, run properties) | 90% |
| Add comment anchored to text | ~26 | ~575 (comment part, anchor markers, relationship, XML manipulation) | 95% |
| Format text (bold + color) | ~20 | ~478 (find runs, split at boundaries, apply rPr) | 96% |
| Set paragraph format (3 paragraphs) | ~30 | ~80 (load, resolve indices, set properties, save) | 63% |
| Composite: read → search → edit → comment | ~120 | ~1,000 | 88% |
The savings are especially large for tracked changes, comments, and run-level formatting — python-docx has no built-in API for track changes or comments, and text formatting requires complex run-splitting logic. The agent must generate raw OOXML manipulation code (~300–575 output tokens per operation). MCP tools handle this internally with a simple parameter call.
Simple read and paragraph-format operations see smaller savings (~63–76%) since python-docx has clean APIs for these.
Output tokens cost 5× more than input tokens, so eliminating code generation has an outsized cost impact. The one-time schema overhead (~2,500 tokens for 33 tools) pays for itself in 3–5 operations.
MIT
FAQs
MCP server for DOCX document editing — read, edit, format, comment, highlight, and track changes in Word documents
The npm package @knorq/docx-mcp-server receives a total of 112 weekly downloads. As such, @knorq/docx-mcp-server popularity was classified as not popular.
We found that @knorq/docx-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket MCP now lets AI assistants review org alerts, investigate threats using the Socket threat feed, and inspect package files in addition to dependency scoring.
Product
Socket Firewall blocks malicious VS Code and Open VSX extensions before install, protecting developers from compromised editor marketplaces.
Research
More than 140 Mastra npm packages were compromised in a supply chain attack that used a typosquatted dependency to deliver a cross-platform infostealer during installation.