Skip to main content
Glama
README.md
<div align="center">

<img src="icon.png" width="96" alt="Office Live MCP logo"/>

# Office Live MCP

One MCP server that drives **live, open** Word, Excel and PowerPoint documents on macOS and Windows through Office.js.

</div>

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D24.0.0-brightgreen)](https://nodejs.org)

This started as a fork of [kzarzycki/powerpoint-mcp](https://github.com/kzarzycki/powerpoint-mcp) and grew into something bigger. The original idea is brilliant: instead of parsing files on disk, an Office.js add-in inside the running Office app talks to a local bridge server over WebSocket. Your AI assistant edits the document you have open right now, and you watch it happen.

I asked the original author whether he planned to extend this to Word and Excel ([issue #173](https://github.com/kzarzycki/powerpoint-mcp/issues/173)). While waiting for an answer I built it myself, on this branch. Same architecture, two more apps.

## What it does

One bridge server, one add-in taskpane, three Office apps. The add-in detects which host it runs in (PowerPoint, Word or Excel) and every tool call executes inside the live document.

- **PowerPoint**: 27 tools from the upstream project. Inspect decks, edit shapes and text, raw OOXML access, charts, screenshots, speaker notes, and an `execute_officejs` escape hatch.
- **Excel**: 32 new tools. Read and write ranges with values, formulas and number formats, inspect workbooks, format cells, manage worksheets, sort and find, tables, charts, conditional formatting, named ranges, data validation, comments, pivot refresh, sheet protection, plus `execute_exceljs`.
- **Word**: 26 new tools. Read and edit paragraphs, styles and formatting, search and replace, tables, comments, page breaks, tracked changes (read), selection, save, plus `execute_wordjs`.

That is 86 tools on one server. Anything the typed tools do not cover, the execute escape hatch handles with raw Office.js in the right host.

There is also a **reverse direction** for opencode users (optional): an OpenCode Chat tab inside the taskpane that chats with your local OpenCode agent and applies its replies straight into the live document (see [OpenCode Chat](#opencode-chat-in-the-taskpane-reverse-bridge) below).

## Why live matters

File-based tools (openpyxl, python-docx, python-pptx) read and write bytes on disk. They cannot refresh a PivotTable, they silently drop charts and macros, and you only see the result after reopening the file. This server works inside the running app instead: formulas are calculated by Excel itself, edits appear on screen while the agent works, and nothing that Excel owns gets lost.

There is a second advantage that matters just as much. Everything here runs locally on your machine, next to your agent, not inside some hosted sandbox. Cloud Office agents lock you into their environment: your files go up, the tools they offer are the tools you get, and combining them with anything else is a fight against the platform. Here the Office tools are just one part of what the agent can reach. In the same session it can read your mail, query a database, drive a browser, call any other MCP server or plain script, and then put the results straight into the live document. The Office control is a capability, not a cage. That combination is where most of the real value showed up while building and testing this.

## Quick start

**macOS / Linux:**

```bash
npm install -g office-live-mcp

# install the add-in into the Office apps + print your server path
office-live-mcp setup
```

**Windows** — one line in PowerShell (finds/installs Node, installs the package, runs setup):

```powershell
irm https://raw.githubusercontent.com/benjaminfrombe/office-live-mcp/main/install.ps1 | iex
```

`setup` is idempotent — run it again any time. On macOS it sideloads the manifest into each installed Office app (needs Full Disk Access for your terminal; it tells you if macOS blocks it). Then open a document, click the add-in button in the Home ribbon, and add the server to your MCP client as shown under [Connecting an MCP client](#connecting-an-mcp-client). **No bridge to start manually.**

<details>
<summary>Installing from source instead</summary>

```bash
git clone https://github.com/benjaminfrombe/office-live-mcp.git
cd office-live-mcp
npm install
npm run build
node dist/index.cjs setup
```

</details>

## Connecting an MCP client

The default mode is **stdio**: the client (Claude Code, OpenCode, Claude Desktop, …) spawns the server, and the server makes sure a shared bridge daemon is running.

```json
{
  "mcpServers": {
    "office-live-mcp": { "command": "npx", "args": ["office-live-mcp"] }
  }
}
```

(or point `node` at the installed `dist/index.cjs` — `npm root -g` shows where that is)

What happens on connect:

- If no daemon is up, one is started **detached** (`--http --bridge`: taskpane on :8790, MCP on :8792) and it stays up after the client session ends — the Office add-in needs it even when no AI session is open.
- If a daemon is already up (another harness, an earlier session, the machine just rebooted), it is reused. Multiple harnesses share one daemon and see the same live documents.
- If the daemon crashed or died with a reboot, the next client connect brings it back.

Useful extras:

- `office-live-mcp --stop-daemon` — stop the shared daemon (however it was started).
- `~/.office-live-mcp/daemon.log` — daemon log; `~/.office-live-mcp/daemon.env` — optional `KEY=VALUE` lines merged into the daemon environment (e.g. `BRIDGE_TLS=1`).
- Prefer an HTTP MCP client? Start the daemon once (`office-live-mcp --http --bridge`) and connect to `http://127.0.0.1:8792/mcp`.
- Legacy in-process mode (`--stdio --bridge`, everything in one process) still exists; if the bridge port is already owned by another office-live-mcp process (e.g. Claude Desktop's extension host), it relays MCP to that bridge instead of failing.

### Connect your harness

`office-live-mcp setup` prints your exact server path and node executable. Use them in one of these:

**OpenCode** — `~/.config/opencode/opencode.jsonc` (Windows: `%USERPROFILE%\.config\opencode\opencode.jsonc`), `"mcp"` section:

```json
"office-live-mcp": {
  "type": "local",
  "command": ["<node>", "<server path>"],
  "enabled": true
}
```

**Claude Code** — one command:

```
claude mcp add office-live-mcp --scope user -- <node> "<server path>"
```

**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` (Windows: `%APPDATA%\Claude\claude_desktop_config.json`), `"mcpServers"` section:

```json
"office-live-mcp": {
  "command": "<node>",
  "args": ["<server path>"]
}
```

**ChatGPT Desktop & Codex** — the ChatGPT desktop app shares its MCP configuration with Codex: `~/.codex/config.toml` (Windows: `%USERPROFILE%\.codex\config.toml`):

```toml
[mcp_servers.office-live-mcp]
command = "<node>"
args = ["<server path>"]
```

(ChatGPT on the web only reaches remote HTTPS servers, so it needs a tunnel for a local bridge like this one.)

### OpenCode Chat in the taskpane (reverse bridge)

Besides acting as an MCP *client* of this server, OpenCode can also be driven **from inside Office**: the taskpane has an **OpenCode Chat** tab that connects to your running OpenCode service, renders the conversation, and applies replies to the live document. The MCP bridge keeps running in the background — the two directions work side by side.

Quick setup:

```bash
npm run opencode-proxy
```

This local proxy (`http://127.0.0.1:4096`) reads the OpenCode service URL + password from `~/.local/state/opencode/service.json`, injects the auth header, and follows service restarts automatically. Then open the **OpenCode Chat** tab in the taskpane and point it at `https://127.0.0.1:4096` (Office's WKWebView blocks plain-`http` fetches from an HTTPS taskpane — a "Load failed" status usually means exactly this).

What it gives you:

- **Chat with live context** — the first prompt of a session carries an invisible preamble (open document, live-MCP instructions) and every prompt carries the active slide + selected shapes, so "this slide" just works.
- **+ Selection** — paste the current document selection into the input as context.
- **Image paste** — paste screenshots into the input as inline attachments.
- **Reasoning strip** — live streaming of the model's reasoning while it works; click it mid-stream to expand the full text, click again to collapse.
- **Question forms** — when the agent calls the `question` tool, the pending form surfaces as an answerable card in the pane (works across sessions: a question asked in another OpenCode window shows up here too; answering or dismissing settles it everywhere).
- **Model picker** — switch the session's model from the action row under the input; the choice is remembered per session.

Full details (SSE handling, session model, testing): [docs/opencode-mode.md](docs/opencode-mode.md).

### Optional: the ribbon icon (HTTPS)

Everything works over plain HTTP except one cosmetic detail: Office refuses to load the **ribbon icon** over HTTP, so the button shows a generic placeholder. The add-in, taskpane and bridge connection are unaffected.

On **macOS**, setup now handles this for you when [mkcert](https://github.com/FiloSottile/mkcert) is installed: it generates the localhost certificate, trusts it, flips `BRIDGE_TLS=1` in the daemon env, and installs the HTTPS manifests — the daemon then serves `https://localhost:8791`. So:

```bash
brew install mkcert && mkcert -install   # one-time CA trust (asks your password)
office-live-mcp setup                    # re-run: switches everything to HTTPS
```

If mkcert is not installed, setup prints these commands as a hint and keeps running over HTTP. To undo, remove the `BRIDGE_TLS=1` line from `~/.office-live-mcp/daemon.env` and rerun setup.

On **Windows**, setup asks whether you want the real ribbon icon. Answering **yes** generates a localhost + hostname TLS certificate, trusts it via `certutil` (Windows shows a one-time confirmation dialog — choose **Yes**), flips `BRIDGE_TLS=1` in the daemon env, and installs the HTTPS manifests. Plain HTTP never shows the real icon on Windows — verified across every combination of headers, hosts and cache states on Office 16.0.20527 — so the question is the only supported path to the icon. To undo, remove the `BRIDGE_TLS=1` line from `%USERPROFILE%\.office-live-mcp\daemon.env` and rerun setup.

## Windows installation

Open **PowerShell** (Start → type "powershell" → Enter) and paste this one line — it finds or installs Node.js, installs the package, and runs `setup`:

```powershell
irm https://raw.githubusercontent.com/benjaminfrombe/office-live-mcp/main/install.ps1 | iex
```

Already installed the package yourself? Then all you need is:

```bat
office-live-mcp setup
```

Verified on Windows 11 (ARM64, Office Insider 16.0.20527). Recent Windows Office builds reject the old sideload shortcuts (Developer-registry manifests only load under a debugger, the new "Apps" storefront never queries custom catalogs, and neither the classic nor the new dialog offers an "Upload My Add-in" option), so the supported route is a **shared folder catalog** — `setup` automates all of it.

What it does:

1. Copies `dist/` and `addin/` to `%LOCALAPPDATA%\office-live-mcp`, keeping only the manifest variants that match the daemon transport (HTTPS or plain) so the catalog lists exactly one add-in per Office app.
2. Registers a trusted add-in catalog in the registry (HKCU, no elevation needed) pointing at that folder through a UNC path. Office only trusts network paths for custom add-ins — that is a Microsoft requirement. In practice no share has to be created: setup uses, in order, an `OLM_CATALOG_UNC` override → a dedicated `OfficeLiveMCP` share (created automatically in an elevated terminal) → the built-in admin share (`\\localhost\C$`), which exists by default on admin machines.
3. Asks whether you want the **real ribbon icon**: HTTPS bridge + trusted certificate (one-time Windows trust dialog). Plain HTTP always renders the generic placeholder icon on Windows, so this is the only way to get the real one.
4. Offers to register the MCP server in your **OpenCode** config (`~/.config/opencode/opencode.json(c)`) when one is detected — plain-JSON files are merged, JSONC files with comments are left untouched with a manual hint.
5. Prints your server path and node executable, plus the link with copy-paste MCP client examples for every harness.

Then the one step no installer can do, because Office requires it:

6. **Close and reopen the Office app** → **Home → Add-ins → Advanced...** → **SHARED FOLDER** tab → select *Office Live MCP* → **Add**.

> **Why not an HTTPS catalog (no UNC at all)?** The bridge can emulate a SharePoint app catalog over `https://localhost:8791` (`OLM_HTTPS_CATALOG=1`, see `server/sharepoint-catalog.ts`), and Office would then list the add-in under MY ORGANIZATION. This worked on Office builds up to 16.0.20430, but Microsoft fully retired SharePoint add-in catalogs on April 2, 2026 — current builds still probe the catalog yet discard the results, so the route is dead on modern Office. The UNC route above is the only supported one.

Notes:

- The daemon's environment file lives at `%USERPROFILE%\.office-live-mcp\daemon.env`, its log at `%USERPROFILE%\.office-live-mcp\daemon.log`.
- Use `manifest.xml` for PowerPoint, `manifest.word.xml` for Word, `manifest.excel.xml` for Excel. All point the taskpane at `http://localhost:8790`.
- As on macOS, the ribbon icon stays a placeholder unless the bridge runs over HTTPS and the manifests point at `https://localhost:8791` — on Windows, setup's icon question arranges all of that for you (see "Optional: the ribbon icon" above). Verified: over plain HTTP the icon never renders on Windows, whatever the response headers say.
- If a build refuses plain-HTTP catalogs, the bridge can also emulate a SharePoint-style HTTPS catalog (`server/sharepoint-catalog.ts`, enabled with `BRIDGE_TLS=1`): Office enumerates `https://<host>:8791` as a corporate catalog and the same manifests are served from there.

## How it is tested

Two layers, because they catch different bugs.

The mock suite (428 tests) verifies tool registration, argument handling and the generated Office.js code, plus the stdio→daemon proxy (auto-start, discovery, session handling, SSE parsing, stop). It is fast and runs on every change.

The live suite runs every tool against a real open document. This is where the mock tests turned out to be insufficient: live testing caught three real API bugs the mocks could never find. `Range.findAllOrNullObject` does not exist on this host, `DataValidationRule` takes a type-keyed object rather than a `{ type, ... }` envelope, and calculation lives on `workbook.application`, not `workbook`. All fixed and now covered by both layers.

## Credits

This project stands on the work of others.

- [kzarzycki/powerpoint-mcp](https://github.com/kzarzycki/powerpoint-mcp) (MIT): the bridge architecture, the PowerPoint tool modules and the add-in are his. This fork exists because of it.
- [mindstone/mcp-servers](https://github.com/mindstone/mcp-servers) (FSL-1.1-MIT): studied as a reference for Word and Excel add-in design. No code from it is included, its license does not allow that, so the Word and Excel tools here are an independent implementation.
- The live Word MCP projects ([kennypeh85/word-mcp](https://github.com/kennypeh85/word-mcp), [HelloWorld-Open/word-mcp-server](https://github.com/HelloWorld-Open/word-mcp-server), [Han-ops-dev/word-mcp-server](https://github.com/Han-ops-dev/word-mcp-server), all MIT) and [sbroenne/mcp-server-excel](https://github.com/sbroenne/mcp-server-excel) (MIT) shaped which tools were worth building. Design references only, no code.
- The icon uses the [Tabler Icons](https://github.com/tabler/tabler-icons) bridge glyph as a starting point for the ring mark (MIT).

Full attribution in [NOTICE](NOTICE).

## Status

Working on macOS with desktop Word, Excel and PowerPoint, and verified on Windows 11 ARM64 with PowerPoint: stdio auto-daemon, OpenCode and Claude Desktop as MCP clients, and live edits through the add-in. PowerPoint Web works for the upstream tool set. The Word and Excel tool surfaces are young: they cover what I actually needed, and the escape hatch covers the rest. Expect rough edges and please open issues.

## License

MIT, like the upstream project. See [LICENSE](LICENSE).

TDQS

B3.3/5.0

Scored across 88 tools

Disambiguation3/5

Across Word, PowerPoint, and Excel the tool purposes are mostly separable, but the PowerPoint inspection cluster (inspect_slide, scan_slide, preview_deck, read_deck_text, inspect_deck) and the XML/edit escape-hatch cluster (edit_slide_xml, edit_slide_zip, edit_shape_paragraphs, execute_officejs) have overlapping use cases. Descriptions help, but misselection is still plausible with 88 tools.

Naming Consistency4/5

Names are overwhelmingly snake_case with a verb_noun pattern, and domain-specific terms are used consistently within Word, PowerPoint, and Excel. There are minor deviations such as screenshot_slide, freeze_panes, and get_local_copy, but the convention remains readable.

Tool Count1/5

88 tools is an extreme tool count for an MCP surface, even for a multi-application Office server. Many fine-grained operations could be consolidated or handled by the generic execute_* escape hatches, so the set is far beyond a well-scoped count.

Completeness4/5

Coverage is strong across all three Office domains: Word paragraphs, tables, comments, properties, and content controls; PowerPoint slides, shapes, notes, charts, images, and XML; Excel ranges, sheets, tables, charts, formatting, comments, protection, and PivotTables. A few lifecycle gaps, such as slide/table deletion, likely require the generic execute_* fallback.

Maintenance

ActivityNo data
ResponsivenessOutdated data