Docx Mcp Server

CI

A local MCP server for reading and editing Word (.docx) documents. Works with Claude Code, Cursor, and any MCP-compatible client.

40 tools for document content, formatting, comments, page layout, and track changes — all running locally via stdio with no file uploads.

Features

Category	Tools
Read	read_document, get_document_info, search_text, list_images, get_paragraph_format, ensure_anchors
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	read_table_structure, read_table_cell, edit_table_cells, edit_table_paragraphs, delete_table_paragraphs, insert_table_paragraphs
Footnotes	read_footnotes

Track changes

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.

Stable anchors

Paragraphs are normally addressed by integer block index, but every insert/delete shifts the indices of later blocks — so a multi-step edit has to re-read after each change. Anchors fix this: an anchor is a stable id (Word's w14:paraId) that stays attached to its paragraph across index shifts.

• Run ensure_anchors once to assign anchors to every paragraph and get the full index→anchor map (most Word-authored documents already carry anchors; the call is idempotent).
• search_text returns each match's anchor, and read_document with show_anchors: true prints them inline.
• The edit tools (edit_paragraphs, delete_paragraphs, set_paragraph_formats, set_headings, insert_paragraphs) accept an anchor (or anchors) as an alternative to paragraph_index. Editing also auto-assigns an anchor to each touched/inserted paragraph and insert_paragraphs returns the new anchors, so a pipeline can keep editing without re-reading.

v1 anchors cover top-level (direct-body) paragraphs; paragraphs inside tables or content controls are not anchored.

Page layout

get_page_layout / set_page_layout support:

• Page size presets: A3, A4, A5, B4, B5, Letter, Legal
• Margin presets: Normal, Narrow, Wide, JP Court 25mm, JP Court 30/20mm
• Custom values in millimeters for page size and individual margins
• Orientation (portrait / landscape)

Quick start

Option 1: Install from npm

npm install -g @knorq/docx-mcp-server

Then add to your MCP config (see Configuration below).

Option 2: Use npx (no install)

Just add the config — npx downloads and runs it automatically:

{
  "mcpServers": {
    "docx-editor": {
      "command": "npx",
      "args": ["-y", "@knorq/docx-mcp-server"]
    }
  }
}

Option 3: Build from source

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

Configuration

Claude Code

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"]
    }
  }
}

Cursor

Add to your MCP server configuration in Cursor settings:

{
  "mcpServers": {
    "docx-editor": {
      "command": "npx",
      "args": ["-y", "@knorq/docx-mcp-server"]
    }
  }
}

Using a local build (without npm)

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"]
    }
  }
}

Distributing to others

Via npm (recommended)

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.

Via zip / git

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.

Tool reference

Reading

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

get_paragraph_format — Introspect a paragraph's formatting (style, heading level, alignment, numbering, indentation in twips, spacing in points). Use it to find a copy_format_from source or debug why two paragraphs render differently. Values match the units set_paragraph_formats accepts.

file_path, paragraph_index

ensure_anchors — Assign a stable anchor (w14:paraId) to every top-level paragraph that lacks one and return the index→anchor map. Idempotent. See Stable anchors.

file_path

Editing

All editing tools accept track_changes (default true) and author (default "Claude"). The paragraph tools below accept an anchor (or anchors) in place of paragraph_index for index-shift-proof targeting — see Stable anchors.

replace_texts — Apply one or more find/replace operations in a single open/save cycle. Handles text spanning multiple runs.

• Under track_changes: false, items are applied sequentially: a later item can match text produced by an earlier item.
• Under 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. Target each by paragraph_index or anchor. A \n in new_text is a paragraph break: untracked edits split it into separate paragraphs (each inheriting the original numbering/indentation), tracked edits keep one paragraph and render \n as a soft line break.

file_path, edits (array of {paragraph_index? | anchor?, new_text}), track_changes?, author?

insert_paragraphs — Insert one or more paragraphs in one operation. Place each by position (block index) or anchor + placement ("before"/"after"); returns the new paragraphs' anchors. A \n in text is a paragraph break (untracked: one paragraph per line; tracked: soft line break). When several paragraphs share the same position, they land in the document in the reverse of array order — list them back-to-front or use separate calls (anchor placement preserves array order).

file_path, paragraphs (array of {text, position? | (anchor + placement), style?, num_id?, num_level?, copy_format_from?, copy_format_from_anchor?}), track_changes?, author?

delete_paragraphs — Delete one or more paragraphs or table blocks in one operation. Target by paragraph_indices (paragraph or table) and/or anchors (paragraph only).

file_path, paragraph_indices?, anchors?, track_changes?, author?

Formatting

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 targets paragraphs by indices and/or anchors and bundles the formatting to apply to them.

file_path, groups (array of {indices?, anchors?, 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. Target each by paragraph_index or anchor.

file_path, headings (array of {paragraph_index? | anchor?, level})

Structure

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.

Review

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

Track changes

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

Page layout

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?

Headers and footers

read_header_footer — Read the text content of all headers and footers.

file_path

Tables

read_table_structure — Inspect a table without reading the whole document: row/column dimensions and a short preview of every cell, plus each cell's merge info (gridSpan / vMerge). Indices are physical w:tc positions, matching read_table_cell / edit_table_cells.

file_path, block_index

read_table_cell — Read a single cell's paragraphs (text + style/alignment/numbering) and merge info, without reading the whole document.

file_path, block_index, row_index, col_index

edit_table_cells — Replace the text content of one or more table cells in a single open/save cycle. Cells can span different tables. A \n in new_text is a paragraph break: untracked edits replace the whole cell, turning each line into its own paragraph (so re-editing leaves no stale lines); tracked edits diff-replace the cell's first paragraph and render \n as a soft line break.

file_path, edits (array of {block_index, row_index, col_index, new_text}), track_changes?, author?

edit_table_paragraphs — Edit one specific paragraph inside a cell (cell-local paragraph_index) without replacing the whole cell. For surgically changing a single line of a multi-paragraph cell (e.g. one numbered-list item).

file_path, edits (array of {block_index, row_index, col_index, paragraph_index, new_text}), track_changes?, author?

delete_table_paragraphs — Delete one specific paragraph inside a cell. Keeps a blank paragraph if the deleted one was the cell's last (so the cell stays valid); real Word numbering renumbers the rest automatically.

file_path, targets (array of {block_index, row_index, col_index, paragraph_index}), track_changes?, author?

insert_table_paragraphs — Insert a paragraph inside a cell at a cell-local position (-1/out-of-range appends). Supports num_id/num_level and copy_format_from (a paragraph index within the same cell).

file_path, inserts (array of {block_index, row_index, col_index, position, text, style?, num_id?, num_level?, copy_format_from?}), track_changes?, author?

Footnotes

read_footnotes — Read all footnotes with their IDs and text content.

file_path

Why MCP tools instead of raw Python?

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

Scenario comparison (output tokens, measured from actual code)

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 40 tools) pays for itself in 3–5 operations.

Requirements

• Node.js 20+

License

MIT