WordMcp — Microsoft Word MCP Server

An MCP server that lets AI assistants drive Microsoft Word for Windows through COM automation: open documents, read and edit text, manage paragraphs and tables, set document properties and export to PDF.

Windows only. A local installation of Microsoft Word is required — this server automates the real application, it does not parse .docx files.

Requirements

Installation

VS Code

A thin extension in vscode-extension/ registers the server with VS Code, so there is nothing to configure by hand. It does not bundle the server; it launches it through dnx, which means the server updates without a new extension release.

Build and install it from a checkout:

cd vscode-extension
npx @vscode/vsce package
code --install-extension word-mcp-0.1.0.vsix

Then run MCP: List Servers from the Command Palette and start Word.

As a .NET tool

dotnet tool install --global WordMcp.McpServer

The tool is then available as mcp-word.

mcp-word --version
mcp-word --help

To update or remove it later:

dotnet tool update --global WordMcp.McpServer
dotnet tool uninstall --global WordMcp.McpServer

To run an unreleased build instead, pack it locally and install from the output folder:

dotnet pack src\WordMcp.McpServer\WordMcp.McpServer.csproj -c Release -o artifacts
dotnet tool install --global --add-source .\artifacts WordMcp.McpServer

Without installing

The server is listed in the MCP registry as io.github.trsdn/mcp-server-word. Clients that resolve packages themselves can run it through dnx, which fetches the version on demand instead of keeping a global tool around:

{
  "servers": {
    "word": {
      "type": "stdio",
      "command": "dnx",
      "args": ["WordMcp.McpServer@0.1.0", "--yes"]
    }
  }
}

Client configuration

The server speaks stdio.

VS Code / GitHub Copilot

.vscode/mcp.json:

{
  "servers": {
    "word": {
      "type": "stdio",
      "command": "mcp-word"
    }
  }
}

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "word": {
      "command": "mcp-word"
    }
  }
}

Copilot CLI

copilot mcp add word --command mcp-word

Concepts

Every operation runs inside a session. A session owns one Word instance and one open document, identified by a session_id such as word-a1b2c3d4e5f6g.

file(open|create) ──► session_id ──► text / paragraph / table / document ──► file(save) ──► file(close)

• Paths must be absolute (C:\Users\me\Documents\report.docx).
• Supported input formats: .docx, .docm, .doc, .dotx, .dotm, .rtf.
• The document must not be open in Word already — WordMcp needs exclusive access.
• Word runs invisibly in the background and is terminated when the session closes.

The session service

Sessions normally live inside the MCP server process and disappear with it. WordMcp.Service.exe is an optional background daemon that holds them instead, so a session survives a restarted client and can be shared by several of them:

WordMcp.Service.exe --daemon [--idle-minutes 30]   # listen until idle or stopped
WordMcp.Service.exe --status                       # what is it doing?
WordMcp.Service.exe --stop                         # save open documents and exit

Starting it by hand is rarely necessary — a client configured to use it starts it on demand. The pipe it listens on embeds your SID and is ACL'd to it, so sessions are never shared between accounts. It exits on its own once no session has been open for the idle timeout.

To use it, set WORDMCP_SERVICE_MODE=daemon for the MCP server. Every tool call then travels to the daemon instead of running in the server's own process. Without it the server keeps sessions to itself, which is what a single client wants: no second process and no startup wait.

Tools

Seventeen tools, each with an action parameter.

file — session lifecycle

file(action: "open", path: "C:\\Users\\me\\Documents\\report.docx")
// → { "sessionId": "word-a1b2c3d4e5f6g", "fileName": "report.docx", ... }

text — content

Character positions come from get and find and are Word range offsets.

paragraph — structure

Paragraph indices are 1-based, matching Word.

table — tables

document — metadata and export

image — pictures

field — fields and tables of contents

section — sections and page setup

header-footer — headers and footers

kind selects header or footer, type selects primary, first-page or even-pages.

style — styles

style_type selects paragraph, character, table or list. Pass in_use_only: false to list for the full set, which is over 370 entries on a localized Word.

style(action: "create", session_id: "...", name: "Callout", base_style: "Normal")
style(action: "modify", session_id: "...", name: "Callout",
      font_size: 11, bold: true, color: "#C00000", space_after: 12)

list — bullets and numbering

Omitting end_index applies the action to start_index alone.

list(action: "apply", session_id: "...", start_index: 2, end_index: 5, list_type: "number")
list(action: "set-level", session_id: "...", start_index: 3, end_index: 4, level: 2)
list(action: "restart", session_id: "...", start_index: 6)

comment — review notes

add comments the whole paragraph unless anchor_text names a phrase inside it. Indexes shift after delete, so list again before deleting a second comment.

comment(action: "add", session_id: "...", paragraph_index: 4,
        text: "Source?", anchor_text: "fifteen percent")
comment(action: "list", session_id: "...", unresolved_only: true)

revision — tracked changes

Omitting index on accept/reject handles the whole document, headers and footers included.

revision(action: "set-tracking", session_id: "...", enabled: true)
revision(action: "accept", session_id: "...")

bookmark — stable references

Names must start with a letter and may only contain letters, digits and underscores. Bookmarks survive edits elsewhere in the document, which makes them the reliable way to refer back to a passage once paragraph indexes have shifted.

bookmark(action: "add", session_id: "...", name: "Intro", paragraph_index: 2)
bookmark(action: "add", session_id: "...", name: "Growth",
         paragraph_index: 4, anchor_text: "fifteen percent")
bookmark(action: "get-text", session_id: "...", name: "Intro")

footnote — footnotes and endnotes

kind selects footnote (default) or endnote; the two are separate collections in Word with independent numbering. This is the only way to reach footnote text at all — text(get) returns the body story and never the notes.

footnote(action: "list", session_id: "...")
footnote(action: "add", session_id: "...", paragraph_index: 4,
         text: "Annual report 2025, p. 14.", anchor_text: "fifteen percent")
footnote(action: "add", session_id: "...", paragraph_index: 4,
         text: "Method described in appendix B.", kind: "endnote")

content-control — template fields

Content controls are the structured fields a Word template exposes. Filling them is the reliable way to complete a template — text(replace) on the surrounding text destroys the control and its binding. tag is not unique and updates every match, which is what a template repeating a field expects; id addresses exactly one control.

content-control(action: "list", session_id: "...")
content-control(action: "set-text", session_id: "...",
                tag: "CustomerName", text: "Contoso Ltd")
content-control(action: "set-text", session_id: "...",
                tag: "TermsAccepted", is_checked: true)
content-control(action: "delete", session_id: "...", tag: "Draft",
                delete_contents: true)

screenshot — see the page

Layout questions — page breaks, table widths, image placement, header positions — are far easier to answer from the rendered page than from measurements. The PNG is written to a file and the path returned; include_image: true additionally returns it inline as base64, which is only worth the context when the image is going to be looked at.

dpi defaults to 150. Use 96 for a quick layout check and 300 for something close to print.

screenshot(action: "page", session_id: "...", page: 2)
screenshot(action: "page", session_id: "...", page: 1,
           output_path: "C:/temp/page1.png", dpi: 300, include_image: true)

Responses

Every tool returns JSON. Failures are reported as structured payloads, never as a transport error:

{
  "success": false,
  "isError": true,
  "tool": "text",
  "action": "Replace",
  "errorType": "KeyNotFoundException",
  "errorMessage": "Session 'word-unknown' not found."
}

Known behaviour and pitfalls

• document(save-as) also saves the original. Word has no format-changing "save a copy" API. For any target other than PDF the server calls SaveAs2(target) and then SaveAs2(original), which persists pending changes to the original file as a side effect. Use export-pdf when you need a side-effect-free export.
• Colours are hex RGB (#0078D4). The server converts to the BGR value Word expects.
• Rights-protected documents (IRM/AIP) are rejected before Word is launched.
• A document open in Word blocks the session — close it first.
• Word dialogs stall automation. If a call times out, check for an open dialog on the desktop.
• Style names are English. Built-in styles (Heading 1, Title, Table Grid, …) are translated to Word's language-independent style ids, so they work on localized installations. Any other name is passed to Word as-is, which is how custom and localized styles are addressed. Note that Word reports styles under their localized name (Überschrift 1 on a German install), which is why style(list) returns both name and english_name — send english_name back when it is present.
• Built-in styles cannot be deleted. style(delete) rejects them with a clear message instead of passing Word's generic COM error through. A custom style that is still applied to a paragraph cannot be deleted either; set those paragraphs to another style first.
• New documents are written directly, not via Word. file(create) writes an empty .docx/.docm package itself and then opens it. Creating documents through Word instead is unreliable on machines signed in to Microsoft 365, because AutoSave claims the new document for OneDrive and silently ignores the requested local path.
• Merged table cells are returned as empty strings by table(read).
• Image sizes are in points, not pixels (72 pt = 1 inch). image(insert) and image(resize) keep the aspect ratio unless lock_aspect_ratio is set to false, so passing only width scales the height along with it.
• image only covers inline pictures. Floating shapes, text boxes and charts are left untouched and do not appear in image(list), so their presence does not shift image indexes.
• A table of contents only lists heading paragraphs. field(insert-toc) returns entry_count: 0 for a document without heading styles — apply Heading 1/Heading 2 via paragraph(add|set-style) first, then run field(update-toc).
• field(update-all) also walks headers and footers. Word's Document.Fields covers the body only, which is why page numbers would otherwise never refresh.
• image(insert) with a caption uses Word's caption numbering, so the caption reads Figure 1 <your text> (localized on non-English installations) and participates in a table of figures.
• All measurements are in points, including page margins (1 cm = 28.35 pt, 1 inch = 72 pt).
• section(page-setup) applies paper_size before the margins, because changing the paper size resets them in Word. Without a section_index the setup is applied to every section.
• Headers and footers are inherited between sections. A new section shows the previous section's header until something is written to it. header-footer(set) with a section_index breaks that link automatically, so section 1 keeps its own text.
• first-page and even-pages headers need a section switch. header-footer(set) turns on DifferentFirstPage respectively DifferentOddEvenPages for you — without it Word stores the text but never renders it.
• list(apply) starts a new list by default. continue_previous_list is off, because picking up the numbering of an unrelated earlier list is rarely what was meant. Two numbered lists separated by plain paragraphs stay independent; use list(restart) when Word merges them anyway.
• Only outline-number lists render distinct levels. list(set-level) works on any list, but a plain bullet or number list shows the same marker on every level — the paragraphs are merely indented.
• comment(resolve) often fails on Microsoft 365. Word's modern comments treat every comment added through the API as an unposted draft, and a draft cannot be marked as done. The server reports that as a clear message; delete the comment instead. comment(list) returns resolved: null on installations that do not expose the state at all.
• Comment and revision indexes shift. Deleting a comment or accepting a single revision renumbers everything after it, so run list again between two such calls instead of reusing the old indexes.
• revision(accept|reject) without an index also walks headers and footers. Word's Document.AcceptAllRevisions() covers the body only, the same gap as with field(update-all).
• Tracked changes are recorded only while tracking is on. revision(set-tracking) does not apply retroactively — turn it on before the edits you want recorded.
• Bookmark names are restricted by Word. They must start with a letter, may contain only letters, digits and underscores, and are limited to 40 characters. Spaces, hyphens, dots and non-ASCII letters are rejected before the call reaches Word, which would otherwise fail with a generic COM error.
• Bookmarks are the stable way to refer to a passage. Paragraph indexes shift with every insertion, bookmarks do not. Bookmark a passage once and use bookmark(get-text) to re-read it later.
• bookmark(add) on a paragraph excludes the paragraph mark, so get-text returns the text without a trailing newline. A bookmark over several paragraphs keeps the marks in between.
• text(get) never returns footnotes. Footnotes and endnotes live in their own Word story, so a document that carries its sources in notes looks complete while a part of its content is missing. Call footnote(list) before summarizing or translating anything.
• Deleting a note renumbers the rest. footnote(delete) shifts every following index down, the same trap as with comments and revisions. When removing several notes, work from the highest index downwards.
• Footnotes and endnotes are separate collections. They have independent numbering, and every footnote action defaults to footnotes — pass kind: "endnote" explicitly.
• Filling a template means content-control(set-text), not text(replace). Replacing the text around a content control destroys the control and its data binding; writing through the control keeps both.
• Content control tags are not unique. content-control(set-text) by tag updates every match and reports how many, because a template that shows the customer name in the header and again in the signature block relies on exactly that. Use id when precisely one control is meant.
• content-control(delete) keeps the text by default. Only delete_contents: true removes the content along with the control. Controls locked against deletion are reported instead of silently skipped.
• screenshot(page) renders through a PDF. Word has no API that returns a page as an image, so the server exports the single page with ExportAsFixedFormat and rasterizes it. Unsaved changes are included, and the temporary PDF is deleted afterwards.
• Page numbers come from a fresh repagination. A document that was only ever edited through automation reports a stale page count, so screenshot repaginates first. That also means the page count reflects the current layout, not the one at open time.

Building from source

git clone https://github.com/trsdn/mcp-server-word.git
cd mcp-server-word
dotnet build WordMcp.sln -c Release
dotnet test WordMcp.sln --filter "Category!=RequiresWord"

Project layout

Generated tool layer

Fourteen of the fifteen tools are generated at build time. The command interfaces in src/WordMcp.Core/Commands are the single source of truth for the wire contract:

• [ServiceCategory("section", "Section")] names the tool class, WordSectionTool.
• [McpTool("section", Title = ..., Description = ...)] supplies the tool name and the prompt the model reads.
• [ServiceAction("page-setup")] on each method becomes a value of the generated WordSectionAction enum.
• XML documentation on the interface parameters becomes the parameter descriptions in the MCP schema.

The generator merges the parameters of all actions into one method, so a parameter used by only some actions is emitted as optional. To change the API, edit the interface — never the generated code. file stays hand-written because it manages sessions rather than operating on one.

Inspect the emitted code under src/WordMcp.McpServer/obj/generated. The tests in GeneratedToolContractTests compare the generated surface against the interfaces, so a mismatch fails the build rather than reaching a client.

Tests that need a real Word installation are marked [Trait("Category", "RequiresWord")] and are excluded in CI. Failed integration runs can leave orphaned WINWORD.EXE processes behind, which slow down or block later runs — clean them up with Get-Process WINWORD | Stop-Process -Force before re-running.

Further reading

Troubleshooting

Contributing

Bug reports and feature requests go through the issue templates. Pull requests are welcome; CONTRIBUTING.md covers how to build, how to run the two halves of the test suite, and what it takes to add a tool.

Please read the Code of Conduct first.

Do not file a public issue for a security problem — report it privately as described in the security policy.

License

MIT — see LICENSE.