Why agents need this

Ask an agent to "accept Jane's edits and update the effective date" and most tooling falls apart. python-docx silently drops tracked changes, plain find-and-replace misses text because Word splits it across hidden boundaries, and a single bad write makes Word pop a "repair" dialog when the file is opened.

DocxEngine avoids all of that by editing the document format directly and checking every change before it saves. What the agent gets:

• Clean, token-light reads. Documents come back as Markdown-like text with stable line IDs, never raw XML, so the agent spends its context on content instead of markup.
• Edits that stick. Replace, insert, delete, or rewrite any paragraph without disturbing tracked changes, comments, footnotes, styles, or images.
• Real redlines. Write genuine tracked changes as a named author, then accept or reject them filtered by author or date.
• Safe by default. Every edit is validated against the Word format before it is written, so files open cleanly and Word never "repairs" them.
• A way to check its work. Render any document to PDF or PNG so the agent can visually confirm the result.

The full surface covers comments, tables, styles, sections, lists, images, fields, and mustache-style template fill, plus Markdown ↔ docx conversion. 24 focused tools in total, backed by 476 tests.

Install

DocxEngine ships as an MCP server. Point your agent at it and go: there are no document handles to track and no save step, because every tool takes a file path and saves automatically. Pick your client below.

claude mcp add docx -- uvx docxengine-mcp

codex mcp add docx -- uvx docxengine-mcp

[mcp_servers.docx]
command = "uvx"
args = ["docxengine-mcp"]

{ "mcpServers": { "docx": { "command": "uvx", "args": ["docxengine-mcp"] } } }

{ "mcpServers": { "docx": { "command": "uvx", "args": ["docxengine-mcp"] } } }

{ "mcpServers": { "docx": { "command": "uvx", "args": ["docxengine-mcp"] } } }

{ "servers": { "docx": { "command": "uvx", "args": ["docxengine-mcp"] } } }

{ "mcpServers": { "docx": { "command": "uvx", "args": ["docxengine-mcp"] } } }

uvx runs the server with zero install (install uv). Prefer pip? Run pip install docxengine and use docxengine-mcp as the command.

What the agent sees

The agent never touches raw OOXML. A read returns Markdown-like text with stable anchors and only the formatting that matters:

[P1#a7b2  H1]            Master Services Agreement
[P2#f3c1]                This Agreement is entered into as of {{EffectiveDate}}...
[P3#b2c4  H2]            1. Definitions
[P4#d4e5]                "Confidential Information" means... [comment:C1 by J.Doe]
[T1  3×4 @after:P5]      | Term | Value | ... |
[P12#e7f8  List:ol L1]   First obligation

Each line has a stable ID (P4#d4e5) the agent uses to target edits, so it never has to re-read the whole document mid-task. A typical edit is one call:

→ docx_revision {"path":"contract.docx","op":"accept","filter":{"author":"Jane Doe"}}
← {"accepted":12,"remaining_by_author":{"Bob":3},"note":"Accepted Jane Doe's tracked changes; Bob's 3 revisions untouched."}

See Concepts for how anchors, reads, and validation fit together, and the tool reference for every tool.

How it works

DocxEngine is a deterministic core with no LLM inside: the same call on the same document always produces the same bytes. It edits the OOXML directly (unzip, patch the XML, rezip), coalesces the split runs Word leaves behind, writes real w:ins/w:del redlines, and validates the result before saving. The full design, including the addressing scheme and tool surface, is in ARCHITECTURE.md.

Documentation

Start at docs/README.md.

Repository layout

docxengine/
├── src/            # docxengine package + MCP server
├── tests/          # Test suite
├── spec/           # Language-agnostic JSON tool contract (the source of truth)
├── conformance/    # Shared corpus + renderer fidelity harness
├── examples/       # End-to-end agent flows
├── docs/           # Design docs, tool reference, guides
└── .github/        # CI, release, security scanning, templates

Contributing

Contributions are welcome, especially conformance corpus documents, OOXML edge-case reports, and benchmark tasks. Read CONTRIBUTING.md for the ground rules, development setup, and commit conventions (Conventional Commits with enforced scopes).

Community & support

• Bugs & features - GitHub issues (structured templates)
• Security reports - privately, per SECURITY.md
• Governance - GOVERNANCE.md

License

Apache-2.0. DocxEngine optionally shells out to external renderers/converters under their own licenses; see LICENSING.md.