MCP Directory

How to add Safe Docx to Windsurf

Local MCP server for surgical, formatting-preserving edits to existing Word (.docx) and OpenDocument (.odt) files. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 32★ · stdio · no auth

Windsurf config for Safe Docx

npx -y @usejunior/safe-docx
{
  "mcpServers": {
    "safe-docx": {
      "command": "npx",
      "args": [
        "-y",
        "@usejunior/safe-docx"
      ]
    }
  }
}

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Safe Docx config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Safe Docx's tools become available to Cascade.

Before you start

  • Node.js (run via npx)
  • An MCP client such as Claude Code, Claude Desktop, Cursor, or Gemini CLI

What Safe Docx can do in Windsurf

read_file

Read an existing .docx/.odt file in a token-efficient format (e.g. toon), returning paragraphs with stable 12-char hex paragraph IDs.

grep

Search a document for a pattern and return the matching paragraph(s) and their IDs.

replace_text

Surgically replace old_string with new_string in a targeted paragraph, preserving formatting; accepts an instruction for tracked-change attribution.

insert_paragraph

Insert a new paragraph into an existing document while preserving structure and formatting.

add_comment

Add a comment to a document (works on both .docx and .odt).

get_comments

Retrieve existing comments from a document.

save

Save the edited document to a local path; supports clean and tracked-changes outputs (save_format: clean, tracked, or both).

compare_documents

Compare two documents (or a live editing session against its original) and write a tracked-changes redline — DOCX, or a native ODF redline for .odt that round-trips in LibreOffice.

Security

Runs entirely on your local machine; no document content is sent to external servers. Word template files (.dotx) are rejected — convert to a normal .docx first. No rendering, layout, or pagination guarantees; documents are validated structurally and against ECMA-376, not pixel-by-pixel.

Safe Docx + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Safe Docx config there under the "mcpServers" key and restart the client.

Is Safe Docx safe to use with Windsurf?

Runs entirely on your local machine; no document content is sent to external servers. Word template files (.dotx) are rejected — convert to a normal .docx first. No rendering, layout, or pagination guarantees; documents are validated structurally and against ECMA-376, not pixel-by-pixel.

Does this preserve formatting during edits?

Yes — that is a core design goal. The tool surface is built around surgical operations (replace_text, insert_paragraph, layout controls) that preserve document structure and formatting semantics as much as possible.

Does this require .NET, Python, or LibreOffice in normal runtime usage?

No. Supported runtime usage is JavaScript/TypeScript with jszip and @xmldom/xmldom.

Can this generate documents from scratch?

The @usejunior/docx-core library ships generateDocx(spec) for declarative generation, but the MCP server does not yet expose a generate_document tool. Brownfield editing of existing documents is the primary focus.

View repo Full Safe Docx page