ms-word-mcp

An MCP server that drives a live Microsoft Word on Windows and macOS, so an AI can write and format a document while you work in it.

Status: early release (0.x). Tool names and arguments may still change.

What it is for

• Working beside you. Every write goes through a range, never through your cursor or selection, so you can keep typing while the AI writes elsewhere in the same document. The window scrolls to what it changed (WORD_FOLLOW_EDITS), and each tool call is one Undo in Word.
• Read back after every write. A result says what Word actually holds now, and lists as warnings whatever did not take.
• Every script. Latin, East Asian (Chinese, Japanese, Korean) and complex-script (Arabic, Hebrew...) text each have their own font. East Asian layouts get spacing in grid lines and indents in character widths, line breaking rules, hanging punctuation and emphasis marks; lists can be numbered in full-width digits, ①, 一, ア, 가, א, α, а and more. Vertical text and ruby (furigana) too.
• Styles first. Every character and paragraph property can be set on a style as well as on text, so a document's look is defined once.
• Equations. From LaTeX or UnicodeMath, built by Word's own equation editor, numbered (1), (2)... at the right margin by fields that renumber themselves.
• Official sources. Every member and constant is checked against Microsoft's documentation (docs/reference), and what the documentation leaves unstated is measured on a real Word (docs/PROBES.md).

Tools

The server lists three tools by default (catalog mode): word_describe lists the rest a line each and gives their arguments, word_run runs one and word_run_steps runs several in order. Set WORD_TOOL_MODE=full to list every tool instead.

Every tool that works on a document takes an optional document argument (a full path or file name), so a call lands in the document it names whatever another conversation has chosen.

Setting it up

Requirements: Microsoft Word (Microsoft 365 or 2021+) on Windows 10/11 or macOS, and uv.

Claude Code:

claude mcp add word uvx ms-word-mcp

Other clients (Claude Desktop, Cursor, .mcp.json):

{
  "mcpServers": {
    "word": {
      "command": "uvx",
      "args": ["ms-word-mcp"]
    }
  }
}

Settings

Security

The server runs on your computer with your permissions and talks to one local client over stdio; it opens no port and makes no network request of its own.

An AI using these tools can read and change any document open in Word, open any file Word can open, and save or embed files wherever your account can write or read. Text inside a document, a web page or another tool's answer can try to steer the AI, so check what it does with documents you received from someone else, and approve its tool calls where that matters.

What the server does about it:

• Macros are disabled while it opens a document or creates one from a template. Word would otherwise run them. The document stays open with macros off.
• Fields that reach outside the document are refused and left alone unless you set WORD_ALLOW_ACTIVE_FIELDS (see Settings).
• Network paths are refused unless you set WORD_ALLOW_NETWORK_PATHS.
• A new link goes to http, https, mailto or tel, or to a path relative to the document. A link the document already has is left as it is.

What it does not do: a document opened through these tools does not get Word's Protected View, so open only documents you would open yourself.

To report a vulnerability, see SECURITY.md.

On macOS

• The first call asks for permission to control Microsoft Word (System Settings > Privacy & Security > Automation).
• Word for Mac is sandboxed: it writes without asking only inside ~/Library/Containers/com.microsoft.Word/Data/Documents; saving elsewhere may make Word ask for access.
• word_get_page_image has Word save a PDF next to the document for a moment and draws the page from it. For a document never saved, the PDF goes in Word's own folder, and macOS may ask once whether the app the server runs in may read Word's data. On Windows the page comes from Word directly. Neither captures the screen.
• Each change is its own Undo step (Word for Mac's scripting cannot group them), and a style can be changed but not created. Tools say so in their results.
• Word asks you about each file outside its own folder, so word_insert_picture puts a copy in Word's folder for a moment and reads it there. The first time, macOS may ask once whether the app the server runs in may use Word's data.
• Word for Mac makes a table only in the active document, so inserting a table brings its document forward for a moment and then gives the previously active one back. Columns cannot be added to a table there.

Development

git clone https://github.com/ykuwai/ms-word-mcp.git
cd ms-word-mcp
uv sync
uv run pytest -q                    # no Word needed
uv run python scripts/live_check.py # runs every tool on a real Word, in a scratch document

The live check creates a document, runs the tools on it, prints PASS or FAIL for each step, exports a PDF and closes the document. It touches no other document.

On Windows, while a client has the server running, uv sync cannot replace .venv\Scripts\ms-word-mcp.exe; run the tests with uv run --no-sync, or stop the server first.

Credits

Built with ppt-mcp's design.

License

MIT