word-mcp

An MCP server that lets an AI agent work inside the Microsoft Word that is open on your Windows PC, on local files and on SharePoint / OneDrive documents opened in Word desktop. The agent types straight into your open document while you watch: no closing, no reopening, no saving behind your back.

Built for writing technical documents with an agent:

• the agent reads your codebase and writes whole sections (headings, lists, code blocks, tables, screenshots and diagrams with numbered captions) in one call with word_insert_markdown;
• it reads the whole live document, including what you typed yourself and have not saved, with its images and comments (word_context), and sees pages exactly as Word renders them;
• it notices your edits since it last looked (word_changes) and targets places by heading text, so your own writing and its writing can be mixed safely;
• everything it writes follows the document’s house style: your template’s own heading, body, list, table, code and caption styles (detected from the document, or copied from a template file);
• saving stays your decision (Ctrl+S): the agent never saves unless you ask.

It uses Word’s own COM automation API, so everything happens in the real Word window, and every agent edit is a single Ctrl+Z step.

Requirements

• Windows 10 or 11
• Microsoft Word desktop (Microsoft 365, 2021, 2019 or 2016). Word on the web and Word for Mac do not work.
• Python 3.10 or newer

Install

git clone https://github.com/givhvy/word-mcp.git
cd word-mcp
python -m pip install -r requirements.txt

Check Python can reach Word (prints its version, changes nothing):

python -c "import win32com.client as c; print('Word', c.Dispatch('Word.Application').Version)"

Register with your agent

Use the full path to word_mcp_server.py. The -I flag runs Python isolated from the current directory.

Claude Code

claude mcp add word --scope user -- python -I C:\path\to\word-mcp\word_mcp_server.py

Restart Claude Code. The tools appear as mcp__word__word_context, mcp__word__word_insert, and so on.

Claude Desktop, Cursor, Windsurf, Cline, or any MCP client using JSON config

{
  "mcpServers": {
    "word": {
      "command": "python",
      "args": ["-I", "C:\\path\\to\\word-mcp\\word_mcp_server.py"]
    }
  }
}

Codex CLI (~/.codex/config.toml)

[mcp_servers.word]
command = "python"
args = ["-I", "C:\\path\\to\\word-mcp\\word_mcp_server.py"]

If python is not on PATH for your client, use the full path to python.exe.

Verify (optional)

python -I test_word_mcp.py
python -I test_context.py
python -I test_v2.py
python -I test_styles.py

Each test creates its own scratch documents in your open Word, checks every tool, and closes only what it created. Both should end with ALL CHECKS PASSED.

Guide for agents

The server sends these rules to the agent on connect; they are repeated here.

1. Read first: word_context returns the whole live document in one call: stats, cursor, save state, header/footer, the body as markdown with Word paragraph numbers [pN] (headings #, lists, tables, bold/italic, links, code, tracked changes {-old-}{+new+}, images ![image n: alt, WxH cm]), every comment thread with replies, and footnotes. include_images=true attaches the images; word_page_image(pages="1-3") shows rendered pages.

2. Write sections in one call with word_insert_markdown:

   ## Data flow
   
   Requests go **client -> API -> DB**. See `api/routes.py`.
   
   1. Auth checks the token
      1. Validate signature
   2. Handler runs
   
   ```python
   def handler(req): ...
   ```
   
   | Layer | Tech |
   |---|---|
   | API | FastAPI |
   
   ![Architecture](C:/shots/arch.png "System architecture"){width=14cm}
   

   Images can be a local path (screenshots, draw.io exports), an https URL or a data: URI; png, jpg, gif, svg, emf. The quoted title becomes a numbered “Figure N:” caption. Images are fitted to the text width. Rewrite a section with word_replace_section(anchor="Data flow", markdown=...).

3. Target by text, not just numbers: position="section_end", anchor="Components" appends to a section; position="after", anchor="..." inserts after any paragraph. When editing by number, pass expect (the start of the paragraph’s text): the edit is refused if the user changed it.

4. Before the next edit, word_changes lists what the user changed since your last read (added, removed and changed paragraphs with current numbers, image/comment counts). It is cheap; the agent’s own edits are not reported.

5. Styling is automatic: new content follows the document’s house style (see below). Write plain markdown and do not add direct formatting. word_styles shows which styles will be used.

6. Never save unless the user asks. word_status/word_context show the save and AutoSave state; word_autosave(false) turns AutoSave off for a SharePoint/OneDrive document.

7. Comments: word_add_comment, word_reply_comment, word_resolve_comment, word_list_comments.

8. Several small steps at once: word_batch. Anything without a tool: word_api_search + word_com.

House style (company templates)

Everything the agent writes uses the document’s own styles, detected from the document itself:

If a role is not used yet, a matching style defined by the document’s template is used; otherwise Word’s built-in style. Nothing is copied or duplicated: Word applies the document’s own definitions.

• word_styles shows the detected house style plus the template’s custom styles (font, size, colour).
• word_apply_styles(source) copies all styles from a .dotx/.docx template, a SharePoint URL or another open document, so a blank document takes the company look.
• word_insert_markdown(..., style_overrides={"table": "Company Table", "caption_label": "Fig."}) pins roles; styles="builtin" ignores the house style.

Tools (44)

How it works

• word_mcp_server.py (FastMCP, stdio). One dedicated COM thread owns every Word object; it attaches to the running Word, retries while Word is busy, and reconnects if Word restarts.
• md_to_word.py turns markdown into a WordprocessingML fragment that Word imports with Range.InsertXML: a whole section, images included, in one call, using the document’s own styles.
• docx_context.py reads Document.WordOpenXML (the whole document in one call) and turns it into the markdown view, comment threads and image list. The parse is cached and reused while the document is unchanged; images are decoded only when asked for.
• word_changes keeps a per-document snapshot of what the agent last saw, refreshed after the agent’s own edits, and diffs the live paragraphs against it.
• dump_typelib.ps1 decodes Word’s type library (MSWORD.OLB, found through the registry) into word-api.json for word_api_search; built automatically on first use (about 2 s).

Measured on Word 16 (Microsoft 365), typical desktop:

The largest cost in practice is the number of agent turns, not Word: prefer word_insert_markdown and word_batch over many small calls.

Troubleshooting

Limitations

• Windows and Word desktop only, because it uses COM automation.
• Works on the main document body. Headers and footers can be set, and are shown in word_context. Text boxes are shown in context but are not edited by the dedicated tools; use word_com.
• word_changes and the context cache see text, image, comment and tracked-change edits; a user’s formatting-only change is picked up with word_context(refresh=true).
• SharePoint / OneDrive: open the document in Word desktop (not in the browser). word_open takes the file’s direct URL; sharing links (/:w:/...) may not open through COM.
• Page images do not show comment balloons. Read comments with word_list_comments.