MCP 服务器

docx-mcp

An MCP server for reading, editing, and validating Microsoft Word documents with specialized support for track changes, comments, and footnotes. It enables structural auditing, heading extraction, and precise OOXML-level document manipulation through natural language tools.

README

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 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.