Lets AI coding agents read, search, edit, compare, convert, and save Word and OpenDocument files while preserving document structure.
Also known as UseJunior/safe-docx, @usejunior/docx-mcp, @usejunior/safe-docx
- Stars
- 47
- Tools
- 30
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is Safe Docx MCP?
Safe Docx lets AI coding agents read, search, edit, compare, convert, and save Word and OpenDocument files while preserving document structure. It exposes 30 tools, such as read_file, get_document_outline, get_sections.
Summary generated from the project's README
About Safe Docx MCP server
Editing Word and OpenDocument files through an AI coding agent is the primary function of this local MCP server. It allows developers to perform precise operations like reading, searching, editing, comparing, converting, and saving documents while maintaining the original file structure. This tool is designed for users who need to automate document modifications without destroying the underlying formatting or layout of the files.
To use it, you install the package via npm and configure your MCP client, such as Claude Code or Antigravity, using the absolute path to the executable. The server operates locally on your machine and does not require external API keys or cloud accounts. It distinguishes itself by its ability to produce both clean copies and tracked-changes versions of a document, ensuring that edits remain targeted and visible for human review.
What you can do with it
- 1Perform targeted document editsAsk an AI agent to change a specific clause in a legal document like an NDA.
- 2Generate tracked changes for reviewRequest that the agent save both a final version and a version showing all modifications.
- 3Automate document file managementUse the server to search, convert, and compare different document formats.
Written from the project's README. Every use case is checked against a quote from it.
How to install Safe Docx MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Safe Docx MCP in Claude Code
$ claude mcp add safe-docx -- npx -y @usejunior/docx-mcpInstall Safe Docx MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"safe-docx": {
"command": "npx",
"args": [
"-y",
"@usejunior/docx-mcp"
]
}
}
}Install Safe Docx MCP in VS Code
.vscode/mcp.json
{
"servers": {
"safe-docx": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@usejunior/docx-mcp"
]
}
}
}Install Safe Docx MCP in VS Code CLI
$ code --add-mcp '{"name":"safe-docx","type":"stdio","command":"npx","args":["-y","@usejunior/docx-mcp"]}'Install Safe Docx MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"safe-docx": {
"command": "npx",
"args": [
"-y",
"@usejunior/docx-mcp"
]
}
}
}Install Safe Docx MCP in Codex
$ codex mcp add safe-docx -- npx -y @usejunior/docx-mcpInstall Safe Docx MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.safe-docx] command = "npx" args = ["-y", "@usejunior/docx-mcp"]
Install Safe Docx MCP in Gemini CLI
$ gemini mcp add -s user safe-docx npx -- -y @usejunior/docx-mcpInstall Safe Docx MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"safe-docx": {
"command": "npx",
"args": [
"-y",
"@usejunior/docx-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @usejunior/docx-mcp 0.25.1 in an isolated container with no network and no keys. It answered and listed 30 tools.
Safe Docx MCP tools 30
Read from the server with tools/listread_fileRead-onlyRead document content (DOCX, ODT, or Google Doc). Output is token-limited (~14k tokens) by default with pagination metadata (has_more, next_offset). Use offset/limit to paginate.
get_document_outlineRead-onlyGet a compact structural map of a document's headings (DOCX only). Each entry is `{paragraph_id, text, level, source}`, plus `list_label` (e.g. "Section 1.01") when the heading is numbered; Markdown puts the label before the text. Deterministic sources are `word_style`, `list_metadata`, and `outline_level`, selected in that precedence order and included by default. Heuristic sources are `run_in_header`, `title_with_period`, `title_with_colon`, `title_caps_centered`, and `title_bare`; set include_heuristic_headings=true to include them. JSON preserves levels 1-9; Markdown clamps visual ATX depth to 6. Read-only.
get_sectionsRead-onlyRead DOCX main-document sections in document order. Returns zero-based session-relative section_index values, paragraph/body boundary metadata, page numbering, page size, margins, and header/footer relationship references. Call again after any operation that changes section topology. Read-only.
grepRead-onlySearch paragraphs with regex. Use file_path for session-based search, file_paths for stateless multi-file search, or google_doc_id for Google Docs. ODT supported via file_path (single-file) only.
batch_editActionSingle-agent front door for applying multiple edit steps (replace_text, insert_paragraph) to a document in one call. Validates all steps first, rejects conflicts before applying anything, then executes valid steps sequentially. Two source-proven bonded heading/body insertions may share an anchor and position when both declare the same bonded_pair_id and distinct style_source_id values; unrelated same-slot inserts remain conflicts. Accepts inline steps or a plan_file_path JSON array. Surface: revisionable — every applied step emits native OOXML tracked changes.
replace_textActionReplace text in a paragraph by provider paragraph id, preserving formatting where supported. Supports DOCX, ODT, and Google Docs. To delete an ordinary DOCX body paragraph, pass its complete visible text as old_string and an empty new_string; a clean save removes the paragraph and a tracked save keeps the deletion for review. Do not use this shortcut for paragraphs that carry section properties, are structurally required by a table cell, or own bookmark/comment anchors without inspecting the structure first. Surface: revisionable — DOCX edits emit native OOXML tracked changes (w:ins/w:del/w:rPrChange).
insert_paragraphActionInsert a paragraph before/after an anchor paragraph by paragraph id. DOCX responses include structural_warnings when the placement may slice a hierarchy, mismatch list levels, or renumber a list. Supports DOCX, ODT, and Google Docs. ODT paragraph ids remain stable within the session; new paragraphs receive monotonically allocated ids, and reopening renumbers stored document order. Surface: revisionable — DOCX insertions emit native OOXML tracked changes.
saveActionPersist the current in-memory document session. For DOCX: saves clean and/or tracked changes output. For ODT: saves an .odt package. For Google Docs: checkpoint (default) returns revisionId, or snapshot exports as DOCX. Surface: revisionable — the save report lists both the AI revisions applied and a non-revision change manifest of any package-level mutations (comment/footnote side parts, relationships) that have no tracked-change wrapper.
exportActionExport a document to a portable rendering (Markdown, semantic HTML, or plain text). Writes an output file (default: source path with the format extension, e.g. .md, .html, or .txt) and returns its path, byte count, and the rendered content (under `content`). Intentionally lossy (no round-trip); HTML is the semantic tier, not pixel-faithful. DOCX only — Google Docs is not supported.
convert_to_odtActionConvert a DOCX document to OpenDocument Text (.odt) using the native model-to-model converter (no LibreOffice involved). Writes the .odt (default: source path with the .odt extension), validates ODF packaging safety before writing, and returns the output path plus a `lossiness` summary itemizing every downgraded construct. Conversion is semantic and intentionally lossy: text, headings, bold/italic/underline, hyperlinks, lists, and tables are mapped; richer styling, tracked changes, comments, and headers/footers are not. DOCX in, ODT out — Google Docs and .odt inputs are not supported.
format_layoutActionApply layout controls (paragraph spacing, paragraph alignment and pagination flags, table row height, cell padding). paragraph_properties sets alignment (w:jc) and sets (true) or removes (false) direct pageBreakBefore/keepNext/keepLines; requests that change nothing are no-ops. Google Docs supports paragraph spacing only. Surface: revisionable — DOCX geometry edits emit native property-change revisions (w:pPrChange/w:trPrChange/w:tcPrChange).
format_numberingActionChange one DOCX body paragraph’s direct numbering reference. Use remove=true to drop direct w:numPr, match_paragraph_id to adopt another paragraph’s explicit numbering, or num_id with ilvl to reference an existing numbering definition. This tool does not create numbering definitions or change style-inherited numbering. Effective edits emit a native w:pPrChange; identical requests are no-ops.
Show all 30 toolsShow fewer tools
format_sectionActionPartially update one DOCX section’s page-number restart, page dimensions/orientation, or margins using a zero-based section_index from get_sections. Effective calls emit one native w:sectPrChange and preserve section topology, page-number format, columns, break type, and header/footer references. Orientation is literal and does not automatically swap dimensions. This tool does not create sections or edit header/footer content.
insert_section_breakActionInsert a tracked DOCX section break after a stable direct-body paragraph. The new boundary preserves the containing section’s page setup and header/footer relationship references. The following section inherits current properties by default; set inherit_properties=false to reset non-relationship properties, and optionally provide page-number/page-size/margin overrides in new_section. Call get_sections again after success because section indexes change.
accept_changesActionAccept every supported tracked change in the document body, including inserted and deleted table-row revisions. Returns acceptance stats; unresolvedRowRevisions remains 0 for supported row markers.
accept_ai_editsActionSelectively accept tracked changes by revision id or author in the in-memory session, leaving all other (e.g. third-party reviewer) revisions byte-untouched. This does not write file_path; call save to persist the mutation. Provide revision_ids (array of w:id values) to target specific revisions, or author to accept every revision by one actor. Sweeps document.xml and supported side-story parts (footnotes, endnotes, comments). An ambiguous overlap — a targeted revision structurally containing, or contained by, a non-targeted revision (nested ins/del/move) — hard-errors with code AMBIGUOUS_REVISION_OVERLAP and a structured `overlaps` list unless normalize_first is set (best-effort, no byte-identical promise).
reject_ai_editsActionSelectively reject tracked changes by revision id or author in the in-memory session (restoring their pre-edit state), leaving all other revisions byte-untouched. This does not write file_path; call save to persist the mutation. Symmetric to accept_ai_edits: provide revision_ids or author, sweeps document.xml and supported side-story parts, and hard-errors on an ambiguous overlap (code AMBIGUOUS_REVISION_OVERLAP with a structured `overlaps` list) unless normalize_first is set.
has_tracked_changesRead-onlyCheck whether the document body contains tracked-change markers (insertions, deletions, moves, and property-change records). Read-only.
get_file_statusRead-onlyGet file/session metadata including edit count, normalization stats, and cache info. Supports DOCX, ODT, and Google Docs.
close_fileActionClose an open file session, or close all sessions with explicit confirmation. Supports DOCX, ODT, and Google Docs.
add_commentActionAdd a comment or threaded reply to a document. Provide target_paragraph_id + anchor_text for root comments, or parent_comment_id for replies. Supports DOCX and ODT (ODT backs comments with office:annotation; threaded replies are DOCX-only). Surface: revisionable + package-mutation — the body-story comment reference is tracked (w:ins), while comment text and author metadata are recorded in the save report non-revision change manifest.
get_commentsRead-onlyGet all comments from the document with IDs, authors, dates, text, and anchored paragraph IDs. Range-anchored DOCX comments also expose optional end_paragraph_id, start_run_index, start_char_offset, end_run_index, and end_char_offset fields describing the covered span. Includes threaded replies (DOCX). Supports DOCX and ODT. Read-only.
delete_commentActionDelete a comment and all its threaded replies from the document. Cascade-deletes all descendants. Surface: revisionable + package-mutation — the body-story comment reference removal is tracked (w:del), while comment/reply text cleanup is recorded in the save report non-revision change manifest.
compare_documentsRead-onlyCompare two documents and produce a tracked-changes output document. Provide original_file_path + revised_file_path for standalone comparison, or file_path to compare session edits against the original. DOCX and ODF (.odt) support both modes. DOCX output always uses the revised archive as its package base and publishes tagged revisions; engine, strategy, reconstruction, premerge, and refinement selectors are not exposed. DOCX stats count insertions/deletions as contiguous ranges, expose tagged-token-v1 totals as insertedAtoms/deletedAtoms with atomMetricVersion, report formatChanges separately from modifiedParagraphs, and report detected moves as moves/movedParagraphs with moveFromRanges/moveToRanges (moved content is not also counted as insertions or deletions, so a pure move reports moves > 0 with zero insertions/deletions). When a DOCX input difference is preserved in the output without tracked-change markup (for example a removed section's header or footer, or an unsupported header/footer topology), the response includes `unrepresented_changes` (objects with scope, kind, sectionIndex, for header/footer scopes role, and for the contentControl scope a contentControl identity: a changed `w:sdtPr`/`w:sdtEndPr` is published as the revised properties without markup, because CT_SdtPr admits no revision elements) plus one `warnings` string per entry, and the message carries a WARNING. Both fields are absent when no reportable unrepresented change was detected; the detector covers section properties, selected header/footer stories and content-control properties, so absence is not a guarantee about differences outside that scope. ODF compares at inline granularity (a modified paragraph is marked up in place — only the changed spans are struck or inserted).
get_footnotesRead-onlyGet all footnotes from the document with IDs, display numbers, text, and anchored paragraph IDs. Read-only.
add_footnoteActionAdd a footnote anchored to a paragraph. Optionally position the reference after specific text using after_text. Note: [^N] markers in read_file output are display-only and not part of the editable text used by replace_text. Surface: revisionable + package-mutation — the footnote reference and note text are tracked (w:ins), while footnote-part creation and registration are recorded in the save report non-revision change manifest.
update_footnoteActionUpdate the text content of an existing footnote. Surface: revisionable — note-text changes emit native OOXML tracked changes (w:ins/w:del) inside the footnote body.
delete_footnoteActionDelete a footnote and its reference from the document. Surface: revisionable — the reference and note text are removed as native OOXML tracked deletions (w:del).
clear_formattingActionClear specific run-level formatting (bold, italic, underline, highlight, color, font) from paragraphs. Surface: revisionable — clearing emits a native run-property-change revision (w:rPrChange).
extract_revisionsRead-onlyExtract tracked changes as structured JSON with before/after text per paragraph, revision details, and comments. Table rows inserted or deleted as a whole, and row property changes (w:trPr > w:ins / w:del / w:trPrChange), are reported as records with scope "row", keyed by the row's first paragraph, whose revisions are ROW_INSERTION / ROW_DELETION / FORMAT_CHANGE entries carrying the revision id, author and date. Supports pagination via offset and limit. Read-only - does not modify the document.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubSafe Docx
Edit Word and OpenDocument files with coding agents.
English · Español · 简体中文 · Português · Deutsch
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.
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.
Comparisons
Install
npm install --global @usejunior/safe-docx
Then configure your MCP client with the installed executable's absolute path. For Claude Code:
claude mcp add safe-docx -- /absolute/path/to/safe-docx
Antigravity CLI
Add Safe Docx to ~/.gemini/config/mcp_config.json:
{
"mcpServers": {
"safe-docx": {
"command": "/absolute/path/to/safe-docx",
"args": []
}
}
}
Restart agy, then ask it to edit a .docx file. Antigravity may ask you to approve the MCP server before first use.
See Installation and verification for locating the executable, pinning a version, and configuring clients.
Documentation
- Installation and verification
- Tool reference
- TypeScript library
- Architecture
- Testing and evidence
- Trust and conformance
- Contributing
Standards Conformance
Browse the Safe Docx Conformance Explorer to navigate ECMA-376 sections, OOXML schema declarations, capability claims, explicit non-goals, and measured cross-implementation outcomes.
The generated repository conformance report remains the source-controlled record of targeted sections, non-goals, and verification references.
What Safe Docx Is 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.
Safe Docx MCP questions
How do I add Safe Docx MCP to Claude Code?
Run claude mcp add safe-docx -- npx -y @usejunior/docx-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Safe Docx MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Safe Docx MCP provide?
It exposes 30 tools, including read_file, get_document_outline, get_sections, grep, batch_edit.
How do I install Safe Docx?
Install it globally from npm, then point your MCP client at the installed executable's absolute path.
Can Safe Docx produce tracked-changes output?
Yes. It preserves DOCX structure and can write either a clean copy or a tracked-changes copy.
Does Safe Docx work with Claude Code or Antigravity?
Yes, it can be registered as an MCP server in Claude Code via the add command, and in Antigravity through its mcp_config.json file.
Is Safe Docx a visual Word editor?
No. It is not a visual editor or layout engine and does not offer browser rendering, real-time collaboration, or pixel-level pagination guarantees.
Can Safe Docx handle .dotx templates?
Not directly; .dotx templates must be converted to .docx before use.