DocxEngine

The fast, reliable way for AI agents to create and edit Word documents.

DocxEngine lets an AI agent open a .docx file, read it back as clean text, and make precise edits without corrupting the file or dropping the tracked changes, comments, and formatting that other tools throw away. It runs as an MCP server, so it plugs straight into Claude Code, Codex, Cursor, and any other MCP client.

Install · Quickstart · Tool reference · MCP server · Docs

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 Code

claude mcp add docx -- uvx docxengine-mcp

Codex CLI

codex mcp add docx -- uvx docxengine-mcp

Or add it to ~/.codex/config.toml:

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

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

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

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

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

Any other MCP client

Run docxengine-mcp over stdio, or point the client at this server block:

{ "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

Lane	What you'll find
Start	Installation, quickstart flows, core concepts
Core	OOXML pitfalls, anchors, projection, tracked changes, validation, rendering
Tools	The full tool interface, group by group, plus error design
MCP	Transports, resources, session state, scaling
Conformance	Round-trip fidelity corpus, agent task benchmark
Reference	Glossary, tool schemas, error codes

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.