Repository navigation
Home
A deleted sentence stays in the file until someone accepts the change, and a careless reader will repeat it with confidence.
docx-mcp is a read-only MCP server that lets an AI agent read and search a Word document as it would stand with every tracked change accepted.
简体中文： docx-mcp 是一个只读的 MCP 服务器，让 AI 智能体读取和搜索 Word 文档，返回接受全部修订后的文本，已删除的内容不会被当作正文，文件本身不会被修改。
繁體中文： docx-mcp 是一個唯讀的 MCP 伺服器，讓 AI 代理讀取與搜尋 Word 文件，回傳接受全部修訂後的文字，已刪除的內容不會被當成內文，檔案本身不會被修改。
| What it is | An MCP server with six read-only tools for Word documents, usable as a plain Python library as well |
| Language | Python 3.12 or newer, with lxml and the MCP SDK |
| Tests | 67 passed, run on 2026-11-06 on Windows with Python 3.12.10 |
| Status | Version 0.1.0, installed from source. This repository makes no claim of deployment or production use |
| License | Apache-2.0 |
Documents under review carry two versions of themselves at once, because the old words and the new ones sit side by side in the same file. An agent that cannot separate them may quote a sentence the editor already removed, or miss one the editor added, and nothing in its answer reveals the mistake. docx-mcp gives the agent one consistent reading, the text as it would stand after acceptance, and it cannot change the file.
- MCP server design: six typed tools over stdio, with readable tool errors
- Office Open XML: tracked changes, moved text, split runs, tables, and text boxes
- Safe parsing of untrusted files: no entity resolution, no DTD, no network, and a size limit per part
- API design for agents: stable paragraph addresses that survive pagination
- Test design with generated fixtures and a real subprocess round trip
| Check | Result |
|---|---|
| Full test suite | 67 passed in 12.05 s |
| Round trip |
examples/call_over_stdio.py started the server as a subprocess and called five tools through the MCP client |
| Search for a deleted word | 0 hits for "failed", which the sample document holds only inside a tracked deletion |
| Independent comparison |
pandoc --track-changes=accept gave the same four paragraphs on the sample document |
Code builds every fixture, and each one is an invented document. The server has not yet read a file saved by Word itself, and Limits and Next Steps explains why that matters.
- Getting Started: install it and connect a client
- How It Works: the structure of a tracked change, with one example
- Evidence: tests, real output, and known failures
- Design Decisions: the choices made and what they cost
- Limits and Next Steps: what this does not read
Designed and authored by Daniel Boles; implemented with coding agents. Apache-2.0.