About Safe Docx
Safe Docx is a local MCP server and CLI for reading, searching, editing, comparing, and saving Word (.docx) and OpenDocument files. It is built for coding agents and preserves DOCX structure while producing clean or tracked-changes output. All processing happens on the user's machine.
Key features
- 01Targeted text replacement that leaves other content intact
- 02Clean or tracked-changes output files
- 03Document comparison and revision review
- 04Comment and footnote management
- 05Formatting, numbering, and section adjustments
- 06Local processing without cloud upload
Use cases
- 01Having a coding agent change the governing law in a contract
- 02Comparing two contract versions and producing redlines
- 03Managing comments and footnotes across a document
MCP support
This project is an MCP server that runs over stdio and takes no arguments. It exposes tools for reading, editing, formatting, tracked changes, comparison, comments, and saving to MCP clients.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
26Saved tool list · updated 3w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| file_path | string | No | Path to the DOCX or ODT file. |
| google_doc_id | string | No | Google Doc ID or URL (alternative to file_path). Extract from URL: docs.google.com/document/d/{ID}/edit |
| offset | number | No | 1-based paragraph offset for pagination. Negative values count from end. |
| limit | number | No | Max paragraphs to return. When omitted, output is token-limited to ~14k tokens with pagination. |
| node_ids | array | No | Paragraph selectors. Each accepts a safe-docx `_bk_*` id, or (DOCX only) any other bookmark name — e.g. a host application's own stable paragraph bookmark — whose w:id-paired range covers exactly one paragraph. Exact name match; a point bookmark or a multi-paragraph range is refused. Returned rows always report the paragraph's canonical `_bk_*` id, even when selected by another bookmark name; results are de-duplicated and returned in document order. |
| format | enum | No | toon | json | simple |
| comment_rendering | enum | No | How to render comments in read_file output. Use "paragraph_notes" (default) for paragraph-local comment threads, "inline_markers" to add `[cm-start:N]`/`[cm-end:N]` milestones in TOON output (combined with the thread blocks), "endnotes" to collect threaded comments into a trailing #COMMENTS block in TOON output, or "none" for the legacy output with no comment rendering.none | paragraph_notes | endnotes | inline_markers |
| show_formatting | boolean | No | When true (default), shows inline formatting tags (<b>, <i>, <u>, <highlighting>, <a>). When false, emits plain text with no inline tags. |
| include_fingerprint | boolean | No | When true and format="json", include a portable content_fingerprint ("sha256:nfkc:<32hex>") on each paragraph. Read-only metadata derived from the paragraph's normalized visible text; NOT an edit anchor. Edit tools accept a `_bk_*` ID, or (DOCX only) any other bookmark name whose w:id-paired range covers exactly that one paragraph. No effect on TOON/simple output. Ignored for Google Docs and ODT. |
| include_fingerprint_ordinal | boolean | No | When true together with include_fingerprint and format="json", add duplicate-disambiguation metadata to each paragraph: `content_fingerprint_ordinal` (1-based document-order position among paragraphs sharing the same content_fingerprint), `content_fingerprint_count_in_document` (total paragraphs sharing it, document-wide even under pagination), and `portable_paragraph_ref` ("<content_fingerprint>#<ordinal>"). Read-only disambiguator, NOT an edit anchor; reordering duplicates may change ordinals. No effect without include_fingerprint, and no effect on TOON/simple output. Ignored for Google Docs and ODT. Default: false. |
| include_footnotes | boolean | No | Single-call body + footnotes retrieval. When true and format="json", the response gains a document-wide TOP-LEVEL `footnotes` array — each entry is {id, display_number, ref_paragraph_ids (an ARRAY of the paragraph ids that reference it), paragraphs[] ({text, tagged_text with run-level formatting tags, style})} — preserving multi-paragraph bodies and footnote-internal bold/italic/citation formatting. This top-level array is NOT inlined into content[], so the 1:1 content[] index invariant is preserved. For backward compatibility a lightweight per-node `footnotes` array ({id, display_number, text}) is ALSO attached to each paragraph node it anchors, windowed to the returned slice. When true and format="toon", a trailing `#FOOTNOTES` sidecar block is appended (symmetric with `#COMMENTS`). Footnotes with an empty body or display_number 0 are excluded. No effect on simple output. Ignored for Google Docs and ODT. Default: false. |
Details
From the project README@usejunior/safe-docx
Edit Word and OpenDocument files with coding agents.
Safe Docx is a local MCP server and CLI for reading, searching, editing, comparing, converting, and saving document files. It preserves DOCX structure and can produce clean or tracked-changes output. Documents are processed on your machine.
Example
Ask your coding agent:
Edit NDA.docx. Change the governing law from New York to Delaware.
Save a clean copy and a tracked-changes copy. Do not change anything else.
Safe Docx finds the clause, applies the targeted edit, and writes both files for review. The rest of the document stays outside the requested edit.
Follow the complete editing walkthrough.
Install
npm install --global @usejunior/safe-docx
safe-docx --help
The package installs both safe-docx and safedocx; use safe-docx in new configurations.
Configure An MCP Client
Locate the installed executable with command -v safe-docx (where safe-docx on Windows). Desktop applications may not inherit your terminal's PATH, so configure clients with that absolute path. The server takes no arguments and uses stdio.
Claude Code:
claude mcp add safe-docx -- /absolute/path/to/safe-docx
JSON-based clients, including Antigravity CLI (~/.gemini/config/mcp_config.json):
{
"mcpServers": {
"safe-docx": {
"command": "/absolute/path/to/safe-docx",
"args": []
}
}
}
See installation and verification for pinning a version, inspecting the package before install, and building from source.
Tools
- Read and navigate:
read_file,get_document_outline,get_sections,grep - Edit:
replace_text,insert_paragraph,batch_edit,clear_formatting - Format:
format_layout,format_numbering,format_section,insert_section_break - Tracked changes:
has_tracked_changes,extract_revisions,accept_changes,accept_ai_edits,reject_ai_edits - Compare:
compare_documents - Comments and footnotes:
add_comment,get_comments,delete_comment,get_footnotes,add_footnote,update_footnote,delete_footnote - Save and convert:
save,export,convert_to_odt,get_file_status,close_file
Parameters and behavior for each tool are in the tool reference.
Not Optimized For
Safe Docx is not a visual editor or layout engine. It does not provide browser rendering, real-time collaboration, or pixel-level pagination guarantees. .dotx templates must be converted to .docx before use.
Links
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.