Can your AI agent edit Word documents without losing formatting?
Yes. safe-docx is the MIT-licensed Model Context Protocol server that lets Claude Code, Gemini CLI, Cursor, and any MCP client read and edit existing .docx files surgically — preserving formatting, tracked changes, and comments. It runs locally on your machine.
One command. Three agents. Jump to Quick install ↓.
Using Claude Code? See the Claude-specific safe-docx setup guide.
Quick install
Pick your agent. Each command pulls the latest @usejunior/safe-docx from npm and registers it as an MCP server. safe-docx runs locally on your machine.
Claude Code
claude mcp add safe-docx -- npx -y @usejunior/safe-docxGemini CLI
gemini extensions install https://github.com/UseJunior/safe-docxCursor / generic MCP client
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"safe-docx": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@usejunior/safe-docx"]
}
}
}Restart Cursor; safe-docx appears in the MCP tools panel.
What safe-docx does
Formatting-preserving edits
Surgical text replacement and paragraph insertion that preserve document structure, styles, and review semantics.
Document comparison
Compare two versions of a document and produce tracked-changes output for human review.
Comments and footnotes
Add, delete, and update comments and footnotes programmatically while keeping formatting intact.
Revision extraction
Extract tracked changes as structured JSON for analysis, reporting, or downstream processing.
23 MCP tools across 7 categories
Each tool is typed with Zod schemas and designed for agent consumption.
Reading & Inspection (7)
read_file, grep, get_session_status, has_tracked_changes, get_comments, get_footnotes, extract_revisions
Planning & Batch (3)
init_plan, merge_plans, apply_plan
Text Editing (2)
replace_text, insert_paragraph
Comments & Footnotes (5)
add_comment, delete_comment, add_footnote, update_footnote, delete_footnote
Layout & Formatting (1)
format_layout
Tracked Changes (2)
accept_changes, compare_documents
File Operations (2)
save, clear_session
Use a template, edit with an agent
safe-docx works best on real-world contract structures. Pick a template, install safe-docx, and give your agent a redline instruction. These are the same .docx files our customers actually negotiate.
Bonterms Mutual NDA
Two-party non-disclosure. ~3 pages. Cross-references and signature blocks worth preserving.
View template →YC SAFE — Valuation Cap
The canonical YC SAFE instrument. Valuation cap variable Claude can rewrite cleanly.
View template →Common Paper PSA
Modular services agreement. Schedules, exhibits, change orders — stress test for multi-section navigation.
View template →Trust & reliability
990+
Automated tests
100%
OpenSpec traceability
MIT
Open-source license
View full Allure test report →
Want to see exactly how each primitive behaves? Browse the Safe-DOCX evaluation scenarios and deep dives — illustrated with fixtures, expected results, and tests.
How safe-docx compares
Engineering deep dives
Explore evaluation scenarios from implementing TypeScript-native DOCX editing primitives — illustrated with fixtures, expected results, and tests drawn from safe-docx's traceability suite.
Browse Safe-DOCX scenariosFrequently asked questions
Can Claude read and edit DOCX files?
Yes, with safe-docx as the bridge. Claude can read text from .docx files natively and generate new ones via its file-creation tool. For surgical edits to an existing document that preserve formatting, tracked changes, and comments, safe-docx is the open-source MCP server that adds that capability. After claude mcp add safe-docx -- npx -y @usejunior/safe-docx, your Claude agent has typed tool calls for replacing text, adding comments, comparing versions, and extracting tracked changes.
Is there an MCP server for editing Word documents?
Yes - safe-docx is an MIT-licensed Model Context Protocol server specifically for editing existing Microsoft Word .docx files. It exposes 23 typed tools across 7 categories (text replacement, paragraph insertion, comment management, footnote handling, document comparison, revision extraction, structural queries). It runs locally via npx and works with any MCP-compatible client (Claude Code, Gemini CLI, Cursor).
Does safe-docx preserve tracked changes?
Yes. safe-docx round-trips OOXML <w:ins> and <w:del> elements, the associated <w:rPr> formatting on revision marks, and comment ranges (<w:commentRangeStart> / <w:commentRangeEnd>). When the agent makes an edit, you can choose to wrap that edit in a tracked-change marker so Word's Track Changes view shows the agent's revisions alongside any human ones already in the document.
How is safe-docx different from python-docx?
python-docx is a Python library focused on generating new .docx files programmatically. safe-docx is a TypeScript-native MCP server purpose-built for editing existing documents AI agents need to work with - surgical text replacement, comment manipulation, comparison, and revision extraction, all preserving the original formatting. See the feature-by-feature comparison for specifics on tracked-change handling, OOXML coverage, and round-trip fidelity.
Where does safe-docx run, and does it send my documents anywhere?
safe-docx runs entirely on your local machine as an MCP server process started by your AI client (Claude Code, Gemini CLI, etc.). It reads and writes .docx files on your local filesystem. safe-docx does not send document content to any UseJunior server, third-party server, or cloud service. Network access is required only for the initial npm install and for updates.
Important nuance: safe-docx itself is local-only, but your AI client may upload prompt content (including text extracted from the document) to its own model provider as part of how it processes your request. That data flow is governed by your AI client's terms (Anthropic, Google, etc.), not by safe-docx. If you need a fully air-gapped workflow, pair safe-docx with a local model.
Does safe-docx work with Gemini CLI?
Yes. safe-docx is an MCP server, so any MCP-compatible client can use it. For Gemini CLI: gemini extensions install https://github.com/UseJunior/safe-docx. See Quick install for Claude Code and Cursor.
Is safe-docx open source? What's the license?
MIT. Source on GitHub at UseJunior/safe-docx, npm package @usejunior/safe-docx. Contributions welcome.
Need to generate new documents?
safe-docx edits existing Word documents. To generate new ones from contract templates, use Open Agreements.
Open Agreements — contract template filling