The open-source, standards-grounded DOCX engine for AI agents.

# Turn agent instructions into reviewable Word redlines.

Edit existing Word files with Claude Code, Gemini CLI, Cursor, or another MCP-compatible agent. SafeDocx helps preserve document structure while producing tracked changes and comments people can review in Word.

[Install SafeDocx](#install)[View source](https://github.com/UseJunior/safe-docx)

*   Apache-2.0
*   Runs locally
*   Tracked changes
*   ECMA-376 target subset

[![Monthly npm downloads for @usejunior/safe-docx](https://img.shields.io/npm/dm/@usejunior/safe-docx?label=npm%20downloads&color=374162)](https://www.npmjs.com/package/@usejunior/safe-docx)

Representative edit

## One clause, three review states

.docx

  

OriginalTracked replacementReviewer comment

Section 8. Limitation of liability

In no event will either party's aggregate liability exceed the fees paid during the three months preceding the claim.

Section 8. Limitation of liability

In no event will either party's aggregate liability exceed the fees paid during the ~three months~ twelve months preceding the claim.

Replacement recorded as a tracked change

Section 8. Limitation of liability

In no event will either party's aggregate liability exceed the fees paid during the three months preceding the claim.

**Review note**

Confirm whether the commercial position permits a twelve-month cap.

Illustrative states backed by editing operations SafeDocx exposes—not a live benchmark run.

Built for document review

## Change the wording. Keep the review trail.

### Revise without rebuilding

Replace text and insert paragraphs in existing Word files while preserving their structure and formatting.

### Make changes easy to inspect

Produce tracked replacements or compare versions so reviewers can see what changed before accepting it.

### Keep the discussion with the text

Add and update comments so questions and explanations stay attached to the passage under review.

Keep mechanics out of the prompt

## Let the agent describe the edit. Let the engine handle Word.

Splitting runs and chasing numbering references competes for the same context window as the work users actually care about.

1.  1**Instruction**The user describes the intended change.
2.  2**Agent**Searches context and chooses a typed operation.
3.  3**SafeDocx**Resolves OOXML structure and applies the mutation.
4.  4**Word output**Returns a reviewable file with revisions or comments.

Agent context

Intent, clause meaning, business constraints, reviewer instructions.

Engine boundary

Runs, relationships, numbering, revision markup, comments, and package integrity.

Inspectable evidence

## A result is more useful when you can see how it was scored.

The existing open benchmark runs shared task fixtures through small adapters and checks the resulting document. Scenario outcomes do not imply that every adapter implements the benchmark's full operation surface.

[See the compatibility results](/safe-docx/compatibility.md)

**Task fixture**Input document + expected invariant

**Adapter operation**Produces an output DOCX

**Structural and visual checks**Compare the result with the task invariant

PassPass-divergentUnsupported

Start locally

## Add SafeDocx to your coding agent.

The MCP server runs on your machine. Your AI client and model provider remain separate parts of the data path.

Choose your coding agent  

Claude Code Codex CLI

### Install for Claude Code

You’ll need Node.js/npm and Claude Code installed.

1.  Run this command in your terminal:
    
    ```
    claude mcp add safe-docx -- npx -y @usejunior/safe-docx
    ```
    
2.  Confirm the server is registered:
    
    ```
    claude mcp get safe-docx
    ```
    
3.  Start a new Claude Code session in your document’s folder. Ask it to use SafeDocx to read a Word file, then review the result.
    

### Install for Codex CLI

You’ll need Node.js/npm and the Codex CLI installed.

1.  Run this command in your terminal:
    
    ```
    codex mcp add safe-docx -- npx -y @usejunior/safe-docx
    ```
    
2.  Confirm the server is registered:
    
    ```
    codex mcp get safe-docx
    ```
    
3.  Start a new Codex session in your document’s folder. Ask it to use SafeDocx to read a Word file, then review the result.
    

These commands register the local MCP server and use `npx` to fetch and run the npm package when your agent starts it.

[Setup for other MCP clients](https://github.com/UseJunior/safe-docx)[npm package](https://www.npmjs.com/package/@usejunior/safe-docx)[Test reports](https://tests.safedocx.com/)

Common questions

## SafeDocx FAQ

<details>
<summary>Can Claude read and edit DOCX files?</summary>

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

<details>
<summary>Is there an MCP server for editing Word documents?</summary>

Yes - safe-docx is an Apache-2.0-licensed Model Context Protocol server specifically for editing existing Microsoft Word `.docx` files. It exposes 26 typed tools across 8 categories (structural inspection, text editing, controlled batches, comment and footnote management, tracked-change controls, comparison, and export). It runs locally via `npx` and works with any MCP-compatible client (Claude Code, Gemini CLI, Cursor).
</details>

<details>
<summary>Does safe-docx preserve tracked changes?</summary>

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

<details>
<summary>How is safe-docx different from python-docx?</summary>

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](/comparisons/safe-docx-vs-python-docx.md) for specifics on tracked-change handling, OOXML coverage, and round-trip fidelity.
</details>

<details>
<summary>Where does safe-docx run, and does it send my documents anywhere?</summary>

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

<details>
<summary>Does safe-docx work with Gemini CLI?</summary>

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](#quick-install) for Claude Code and Cursor.
</details>

<details>
<summary>Is safe-docx open source? What's the license?</summary>

Apache-2.0. Source on GitHub at [UseJunior/safe-docx](https://github.com/UseJunior/safe-docx), npm package [@usejunior/safe-docx](https://www.npmjs.com/package/@usejunior/safe-docx). Contributions welcome.
</details>

<details>
<summary>What do I need to get started, and does SafeDocx cost anything?</summary>

SafeDocx is free and Apache-2.0 licensed; no SafeDocx account or subscription is required. Install Node.js/npm and use an MCP-compatible agent, then follow [Quick install](#quick-install). Your AI client or model provider may charge separately. Start with a copy of a document and review the output in Word.
</details>

<details>
<summary>Will SafeDocx work with every Word document?</summary>

SafeDocx targets a subset of the Word document standard. Check the [compatibility results](/safe-docx/compatibility.md) for the scenarios you need, try a copy of your document, and inspect the output in Word.
</details>

Your first edit

## Give your agent a Word file. Get a change you can review.

Start with a copy, ask for a tracked replacement or reviewer comment, and inspect the output in Word.

[Install SafeDocx](#install)