The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Word listing page.
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
.docxfiles.
| OS | Windows 10/11 |
| Runtime | .NET 9 SDK or runtime |
| Office | Microsoft Word 2016 or newer (desktop, not Microsoft Store version) |
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:
Then run MCP: List Servers from the Command Palette and start Word.
The tool is then available as mcp-word.
To update or remove it later:
To run an unreleased build instead, pack it locally and install from the output folder:
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:
The server speaks stdio.
.vscode/mcp.json:
%APPDATA%\Claude\claude_desktop_config.json:
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.
C:\Users\me\Documents\report.docx)..docx, .docm, .doc, .dotx, .dotm, .rtf.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:
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.
Seventeen tools, each with an action parameter.
file — session lifecycle| Action | Purpose |
|---|---|
open | Open an existing document and start a session |
create | Create a new document at path |
save | Save the open document |
close | Save (optionally) and close the session |
list | List all active sessions |
test | Check whether Word can be automated on this machine |
text — content| Action | Purpose |
|---|---|
get | Read the whole text or a character range (start, end, max_length) |
append | Append text, optionally as a new paragraph |
find | Find a term; returns positions and surrounding context |
replace | Replace occurrences (match_case, match_whole_word, replace_all) |
format | Apply bold, italic, underline, font_name, font_size, color to a range |
Character positions come from get and find and are Word range offsets.
paragraph — structure| Action | Purpose |
|---|---|
list | List paragraphs with index, text, style, alignment and outline level |
add | Append a paragraph, optionally with style |
insert | Insert a paragraph before a given index |
delete | Delete a paragraph by index |
set-style | Apply a style such as Heading 1 |
set-alignment | left, center, right or justify |
Paragraph indices are 1-based, matching Word.
table — tables| Action | Purpose |
|---|---|
list | List tables with dimensions and style |
create | Create a table with rows × columns |
read | Read all cells of a table as a row/column matrix |
set-cell | Write a single cell (row, column, text) |
add-row | Append a row |
delete-row | Delete a row |
set-style | Apply a table style such as Table Grid |
document — metadata and export| Action | Purpose |
|---|---|
get-info | Word, character, paragraph, page, table and section counts |
get-properties | Title, author, subject, keywords, comments, company |
set-properties | Update those built-in properties |
export-pdf | Export to PDF without touching the open document |
save-as | Save a copy in another format |
image — pictures| Action | Purpose |
|---|---|
list | List inline images with index, size, alt text and link state |
insert | Insert a picture, optionally with width, height, caption and alt_text |
resize | Resize by width/height or by scale_percent |
replace | Swap the picture behind an index, keeping its size by default |
delete | Delete an image by index |
set-alt-text | Set the alternative text for accessibility |
field — fields and tables of contents| Action | Purpose |
|---|---|
list | List all fields with index, type and field code |
insert-toc | Insert a table of contents (upper_heading_level, lower_heading_level) |
update-toc | Recalculate every table of contents |
update-all | Update all fields, including those in headers and footers |
insert-page-number | Add a page number to the header or footer |
section — sections and page setup| Action | Purpose |
|---|---|
list | List all sections with start type, margins, page size and orientation |
add | Insert a section break (start_type: next-page, continuous, even-page, odd-page) |
page-setup | Set margins, orientation and paper_size for one section or the whole document |
header-footer — headers and footers| Action | Purpose |
|---|---|
get | Read the header or footer of one section or of all sections |
set | Write text, optionally with an alignment |
clear | Empty the header or footer |
kind selects header or footer, type selects primary, first-page or even-pages.
style — styles| Action | Purpose |
|---|---|
list | List styles; by default only the ones the document uses |
create | Add a custom style, optionally based on an existing one |
modify | Change font and paragraph formatting of a style |
delete | Remove a custom style |
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.
list — bullets and numbering| Action | Purpose |
|---|---|
get | Report the list formatting of the paragraphs, including the rendered bullet or number |
apply | Format a paragraph range as a bullet, number or outline-number list |
set-level | Set the list level of a paragraph range (1–9) |
restart | Start the numbering over at a paragraph |
remove | Strip the list formatting |
Omitting end_index applies the action to start_index alone.
comment — review notes| Action | Purpose |
|---|---|
list | List the comments with author, date, text and the commented-on text |
add | Attach a comment to a paragraph or to a phrase inside it |
resolve | Mark a comment as done, or reopen it |
delete | Remove a comment |
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.
revision — tracked changes| Action | Purpose |
|---|---|
list | List the tracked changes and report whether tracking is on |
accept | Accept one revision, or all of them |
reject | Reject one revision, or all of them |
set-tracking | Turn change tracking on or off |
Omitting index on accept/reject handles the whole document, headers and footers included.
bookmark — stable references| Action | Purpose |
|---|---|
list | Bookmarks with name, paragraph index and a preview of the marked text |
add | Bookmark a paragraph, a paragraph range or a phrase inside a paragraph |
get-text | Read the full bookmarked text |
delete | Remove a bookmark; the text stays |
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.
footnote — footnotes and endnotes| Action | Purpose |
|---|---|
list | Footnotes or endnotes with index, reference mark, paragraph and text |
add | Attach a note to a paragraph, or to a phrase inside it |
set-text | Rewrite the text of a note |
delete | Remove a note together with its reference mark |
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.
content-control — template fields| Action | Purpose |
|---|---|
list | Content controls with tag, title, type, lock state and current text |
get | Read the controls addressed by tag or id |
set-text | Fill them; is_checked for checkbox controls |
add | Wrap a paragraph in a new control |
delete | Remove controls, optionally with their contents |
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.
screenshot — see the page| Action | Purpose |
|---|---|
page | Render a page as a PNG |
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.
Every tool returns JSON. Failures are reported as structured payloads, never as a transport error:
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.#0078D4). The server converts to the BGR value Word expects.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.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.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.table(read).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.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.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.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.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.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).revision(set-tracking) does not apply retroactively — turn it on before the edits you want recorded.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.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.footnote action defaults to footnotes — pass kind: "endnote" explicitly.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(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.screenshot repaginates first. That also means the page count reflects the current layout, not the one at open time.| Project | Purpose |
|---|---|
src/WordMcp.ComInterop | Word COM lifecycle: STA threading, sessions, OLE message filter, file validation |
src/WordMcp.Core | Command interfaces, command implementations and result models |
src/WordMcp.Generators.Shared | Source files shared by the generators; not a project of its own |
src/WordMcp.Generators.Mcp | Roslyn source generator that emits the MCP tool classes |
src/WordMcp.McpServer | stdio MCP server exposing the fifteen tools |
tests/WordMcp.Core.Tests | Unit tests plus integration tests against a real Word |
tests/WordMcp.McpServer.Tests | Tool-layer unit tests, no Word required |
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.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.
| Document | Covers |
|---|---|
| docs/architecture.md | The layers, the request flow and how the tool layer is generated |
| docs/com-interop.md | STA threading, releasing COM objects and the Word behaviour behind the pitfalls above |
| CONTRIBUTING.md | Building, testing, adding a tool, cutting a release |
| skills/word-mcp/SKILL.md | An agent-facing guide to using the tools in the right order |
| Symptom | Cause and fix |
|---|---|
Word is not installed or not registered for COM | Install Word desktop; the Microsoft Store version cannot be automated |
Could not load file or assembly 'office' | office.dll was not found in the GAC — reinstall or repair Office |
| Operation times out | A Word dialog is waiting for input; close it and retry |
The file is already open in Word | Close the document in the Word UI |
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.
MIT — see LICENSE.