mcp-server-word

# WordMcp — Microsoft Word MCP Server

<!-- mcp-name: io.github.trsdn/mcp-server-word -->

An [MCP](https://modelcontextprotocol.io) 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

| | |
|---|---|
| OS | Windows 10/11 |
| Runtime | .NET 9 SDK or runtime |
| Office | Microsoft Word 2016 or newer (desktop, not Microsoft Store version) |

## Installation

### VS Code

A thin extension in [`vscode-extension/`](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:

```powershell
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

```powershell
dotnet tool install --global WordMcp.McpServer
```

The tool is then available as `mcp-word`.

```powershell
mcp-word --version
mcp-word --help
```

To update or remove it later:

```powershell
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:

```powershell
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](https://registry.modelcontextprotocol.io/v0/servers?search=mcp-server-word) 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:

```json
{
  "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`:

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

### Claude Desktop

`%APPDATA%\Claude\claude_desktop_config.json`:

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

### Copilot CLI

```powershell
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

| 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 |

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

### `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.

```jsonc
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

| 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.

```jsonc
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

| 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 r