Office MCP Bridge

Drive your installed Microsoft Word, Excel and PowerPoint from any MCP client — on real files, in real desktop windows.

Русская версия

Why

Most "office" MCP servers parse OpenXML files or re-implement a document model. This one is a thin, disciplined bridge to the already installed desktop Office over COM:

• works on the actual .docx / .xlsx / .pptx the user has open, with Office's own rendering, styles, charts and PDF export;

• no cloud, no API keys, no document upload — everything stays on the machine;

• one STA COM thread, serialized calls and a named mutex, so several agent sessions can share Office without corrupting each other;

• attaches to a running Office instance instead of starting a second one.

Related MCP server: Office MCP Server

Features

Requirements

• Windows 10/11 with desktop Microsoft Word, Excel and PowerPoint installed (Microsoft 365 or Office 2016+).

• Python 3.10+ (tested on 3.14).

• Packages: mcp>=1.10,<2 (SDK 2.x renamed FastMCP; this bridge targets 1.x), pywin32>=306.

Word, Excel and PowerPoint are independent — install only what you need; tools for missing apps return a clear error.

Installation

1. Clone

git clone https://github.com/disemay12/office-mcp.git
cd office-mcp

2. Create an isolated environment

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Note the absolute path to the interpreter — every client config below needs it:

(Resolve-Path .\.venv\Scripts\python.exe).Path
# C:\...\office-mcp\.venv\Scripts\python.exe

3. Register the server

The entry point is office-mcp/server.py, started over stdio:

<python.exe> -X utf8 <repo>\office-mcp\server.py

-X utf8 matters: tool arguments and results are UTF-8, including non-ASCII paths.

{
  "mcpServers": {
    "office": {
      "command": "C:\\path\\to\\office-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-X", "utf8", "C:\\path\\to\\office-mcp\\office-mcp\\server.py"]
    }
  }
}

claude mcp add office -- "C:\path\to\office-mcp\.venv\Scripts\python.exe" -X utf8 "C:\path\to\office-mcp\\server.py"

{
  "mcp": {
    "servers": {
      "office": {
        "type": "local",
        "command": [
          "C:/path/to/office-mcp/.venv/Scripts/python.exe",
          "-X", "utf8",
          "C:/path/to/office-mcp/server.py"
        ],
        "timeout": { "startup": 60000, "catalog": 120000, "execution": 300000 }
      }
    }
  }
}

Raise the timeouts: the first call in a session may have to cold-start Word.

Same command + args shape as Claude Desktop; see examples/mcp.json.

4. Verify

Restart the client, then ask:

Call office_status.

A working install answers with the Office apps currently running, the base directory and the Python version. If the tools do not appear, see Troubleshooting.

Tools

Common

Word — 19

Excel — 17

PowerPoint — 13

In every tool the document / workbook / presentation argument may be omitted when exactly one file is open — the active one is used. A file name, a full path, or a string index is also accepted.

Paths

• Relative paths resolve against %USERPROFILE%\Documents\Office MCP.

• Files created without a path (word_create(), excel_create(), ppt_create()) are saved there as word-YYYYMMDD-HHMMSS.docx and so on.

• Absolute paths and ~ are supported.

• Override the base directory with the OFFICE_MCP_BASE_DIR environment variable (set it before the client starts).

• office_open_file hands the file to the default Windows application (useful for PDFs).

Behavior

• Visibility. Word and Excel show by default; visible=false hides the window while the app keeps running. PowerPoint cannot run hidden — its window is always visible.

• Dialogs. DisplayAlerts is off, so Office never asks for confirmation. A modal dialog opened by someone else (file locked, recovery, sign-in) makes the call fail after a 180 s timeout.

• Busy. Calls are serialized. A second session waits up to 60 s, then gets Another Office MCP session is busy.

• Reuse. The bridge attaches to a running instance via GetActiveObject, otherwise it starts one. office_quit terminates the app.

• Macros. Documents open in normal mode; macros are not forcibly disabled. Only use trusted files.

• Saving. PDF export saves the source file first. office_quit without save/force will not close an app holding unsaved work.

Example prompts

• "Create a Word report with a TOC, a table and headers, save it to C:\Temp\report.docx and export it as PDF."

• "Open sales.xlsx, add a Report sheet with a regional summary and a chart, then save."

• "Build a 5-slide deck from this text, add speaker notes, export to PDF."

• "Read the open Word document and rewrite the Summary section shorter."

Slides

A 9-slide deck walking through the same ground as this README — in five minutes. The deck is in Russian; the condensed English version of each slide is below.

01 · Title. OpenCode × Microsoft Office: 53 tools, real files, Windows.

02 · Context. A chat can talk but cannot touch a real Office file. The bridge turns tool calls into COM commands, so the document is produced by Office itself — styles, formulas and charts stay genuine instead of being emulated by an OpenXML parser.

03 · Architecture. Chat → MCP server (stdio, 53 tools) → COM thread (STA, task queue) → Office. A tool call is queued, executed inside the application, and answered with JSON: one serialized path, predictable errors, no races.

04 · Execution. Office servers are apartment-bound; a COM proxy cannot cross threads. Every operation runs on a single STA thread with a task queue. Busy calls are retried, a 180 s timeout catches modal dialogs, and a dead instance is detected by RPC_E_DISCONNECTED and recreated. Running apps are reused via GetActiveObject, new ones start with DispatchEx.

05 · Coordination. The named mutex Local\OfficeMCP_Bridge_Serial serializes calls across processes. A second chat waits 60 s and then gets Another Office MCP session is busy instead of a corrupted document.

06 · Tools. Word 19, Excel 17, PowerPoint 13, common 4. One contract: JSON results, explicit saving, PDF export that saves the source first.

07 · Files. Relative paths resolve under %USERPROFILE%\Documents\Office MCP; unnamed files are created there; OFFICE_MCP_BASE_DIR overrides the base.

08 · Limits. Full COM access under the current user — not a sandbox. PowerPoint is always visible; Word and Excel can be hidden. A modal dialog becomes a timeout, not a hang. No network ports: stdio only.

09 · Summary. One chat, three applications, real files. MCP is the interface, COM is the execution, the mutex is the predictability.

Source deck: docs/presentation/office-mcp.pptx · PDF: docs/presentation/pdf/office-mcp.pdf · full Russian walkthrough: README.ru.md.

Testing

python -X utf8 tests\smoke_test.py       # 49 live operations across Word, Excel, PowerPoint
python -X utf8 tests\mcp_client_test.py  # stdio handshake, 53-tool catalog, real calls

Artifacts are written to %TEMP%-adjacent paths C:\Temp\office-mcp-test and C:\Temp\office-mcp-protocol-test. Both tests launch real Office applications and close them afterwards — save your own work first.

Troubleshooting

Security

The bridge runs as the current Windows user and holds full COM access to Office: it can read, modify, save and delete document content, and launch the applications. There is no sandbox. Do not attach it to untrusted agents, and keep it pointed at the directories you actually need. No network port is opened — transport is stdio only.

License

MIT