Microsoft Office

@mindstone/mcp-server-office

Read and edit Word documents, Excel workbooks, and PowerPoint presentations from desktop Microsoft 365 via an Office Add-in sidecar.

*Desktop-only Office MCP. Edits the Word/Excel/PowerPoint documents the user already has open on macOS or Windows.*

Status

• Version: 0.3.0 · npm
• Auth: None (server.json)
• Tools: 62 (word, excel, powerpoint, setup)
• Surface: desktop-addin
• Machine-readable: STATUS.json

Why this exists

At the time we built this, Microsoft did not ship an MCP server for the *desktop* Office apps, and the community options we found either targeted cloud-stored documents through Microsoft Graph or only worked on Windows. We needed something that could edit a Word document, Excel workbook, or PowerPoint deck the user already has open — on both macOS and Windows — with live access to selections, formulas, and tracked changes. This package bundles the MCP server, the small local helper that talks to Office, and the Office Add-in itself into a single npm install, so the three pieces always ship at the same version.

Example interaction

"In the Excel workbook I have open, fill column D with =B*C for each data row and bold the totals row."

Tools the host calls:

1. rebel_office_excel_set_formula — writes =B *C into each cell in column D.
2. rebel_office_excel_format_range — applies bold to the totals row range.

What the AI gets back

Every tool, including setup, status and input-validation failures, returns JSON in content[0].text. ok: true means the requested operation completed, including setting a value that already had that value. Successful results carry data; failures carry error and set MCP's isError: true.

{"ok":true,"app":"word","action":"read_document","data":{"paragraphs":[]}}

{"ok":false,"app":"excel","action":"write_range","error":{"code":"READ_ONLY","message":"<untrusted-content source=\"microsoft-office-excel\">The file is read-only.</untrusted-content>","fix":"Ask the user to enable editing or save an editable copy before trying again.","retryable":false}}

app is word, excel, powerpoint, or all for setup and status; action names the tool's operation (setup or status for those tools). Unknown or disabled tools and invalid inputs use INVALID_ARGUMENT (McpError(InvalidParams)); other exceptions thrown by handlers use INTERNAL_ERROR. An unknown tool has app: "office" and action: "unknown".

Error codes, fixes and retry guidance come from a local catalog. Unknown Office codes become UNKNOWN_ERROR. retryable means recovery may permit another attempt; after a timeout, read the current state before repeating an edit, because the edit may already have completed. Messages and all strings in data received from Office or the sidecar stay inside envelopes, with embedded closing tags escaped. App, action, codes and fixes stay outside those envelopes.

Undoing edits

Every successful edit includes an undo sentence, also shown at the end of its tool description. This guidance comes from the connector; previous text and formatting values stay in the enveloped data fields.

On current desktop Word and Excel, and PowerPoint on Windows, each edit uses one writing batch, so the user can undo it with Ctrl+Z (Cmd+Z on Mac). A PowerPoint slide with title, subtitle or body takes two: text, then slide. Deleting an Excel worksheet cannot be undone and clears Excel's undo history.

PowerPoint for Mac cannot reliably undo add-in edits with Cmd+Z. Its undo guidance names the existing tools and returned values to reverse an edit. Read the current state first and ask the user if it has changed since the edit. Deleting shapes or slides and applying layouts cannot be reversed exactly with these tools. Neither can restoring empty text or notes, a non-solid fill, no line, previous dimensions or line width of zero, or text formatting changed by update_text. Restoring previous text does not restore its original mixed formatting. Those limitations are stated in the tool's guidance; confirm with the user first. No undo history is stored by the connector.

For Excel read_range and read_table JSON rows, header-derived object keys are enveloped just like headers, including a column named __proto__. Other result keys that are not plain identifiers are also enveloped, including keys containing spaces, punctuation or closing tags. Word get_properties returns customProperties as an array of { name, value } entries; every name is enveloped, including names that look like identifiers and __proto__.

Word text inserts add all text and paragraph breaks first, then give heading and named styles to the whole paragraph, then add only the requested inline bold or italic, preserving the style's formatting.

Relative placements require their target: afterParagraph needs paragraphIndex, and afterSheet needs afterSheet. A paragraph range needs startParagraph, and a specific tracked-change target needs changeIds. If any requested tracked-change IDs are missing, ITEM_NOT_FOUND lists them before any changes are accepted or rejected.

If the Office connection is turned off for the Rebel installation, tools that start it return CONNECTION_DISABLED with retryable: false. Ask whoever manages the installation to re-enable it; Settings cannot override that decision.

Requirements

• Node.js 20+
• npm
• macOS or Windows with Microsoft 365 Word, Excel, and/or PowerPoint installed
• First-run admin prompt on Windows to trust the dev certificate (one-time)

On Windows, the helper registers the generated manifest under the current user's HKCU\Software\Microsoft\Office\16.0\WEF\Developer registry key so the add-in appears in Word, Excel and PowerPoint. This registration needs no administrator access. Run rebel_office_setup with action="uninstall" to remove the registration, then restart any open Office apps. On Windows, the add-in stays removed only while the Office connection is turned off in Rebel, because the connector registers it again whenever it starts.

One-click install

After clicking the button, your host will prompt you to fill: MCP_OFFICE_SIDECAR_STATE.

Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (Microsoft Office)

{

"mcpServers": { "Microsoft Office": { "command": "npx", "args": [ "-y", "@mindstone/mcp-server-office" ], "env": { "MCP_OFFICE_SIDECAR_STATE": "" } } } }

Quick Start

Install & build

cd <path-to-repo>/connectors/office

npm install npm run build

npx (once published)

npx -y @mindstone/mcp-server-office

Local

node dist/index.js

Configuration

Environment variables

Read by the stdio MCP server (`dist/index.js`):

• MCP_OFFICE_SIDECAR_STATE — required. Absolute path to the sidecar state file (JSON). The MCP server reads port and token from this file to talk to the sidecar; the sidecar writes it on startup. The state file's parent directory doubles as the sidecar's state directory (certs, per-app manifests).
• MCP_OFFICE_SIDECAR_DISABLE — optional kill-switch. When set (1), the MCP server refuses to talk to or spawn the sidecar.

Read by the sidecar (`dist/sidecar/cli.js`) — normally set by the MCP server when it lazy-spawns the sidecar, but documented here for hosts that manage the sidecar lifecycle directly:

• MCP_OFFICE_SIDECAR_STATE_DIR — required by the sidecar. Directory for the state file, HTTPS certificates, and generated per-app manifests (manifest.word.xml, manifest.excel.xml, manifest.powerpoint.xml). The MCP server derives this from the parent directory of MCP_OFFICE_SIDECAR_STATE and passes it through automatically.
• MCP_OFFICE_ADDIN_DIR — optional. Absolute path to the built add-in static files (the directory containing taskpane.html, taskpane.js, and assets/). The MCP server sets this to the package's dist/addin/ directory; hosts serving a custom add-in bundle can override it.

Host configuration examples

Claude Desktop / Cursor

The Office connector is designed to be managed by a host application (like Mindstone Rebel) that owns the sidecar lifecycle. Running it directly from Claude Desktop is possible but the host must provide a writable MCP_OFFICE_SIDECAR_STATE path.

{

"mcpServers": { "Office": { "command": "npx", "args": ["-y", "@mindstone/mcp-server-office"], "env": { "MCP_OFFICE_SIDECAR_STATE": "/absolute/path/to/sidecar-state.json" } } } }

Mindstone Rebel

"RebelOffice": {

"name": "RebelOffice", "type": "stdio", "command": "npx", "args": ["-y", "@mindstone/mcp-server-office@0.1.4"], "env": { "MCP_OFFICE_SIDECAR_STATE": "~/Library/Application Support/mindstone-rebel/office-sidecar/sidecar-state.json" }, "description": "Microsoft Office integration — Word, Excel, PowerPoint.", "catalogId": "bundled-office" }

Tools (62)

Setup

• rebel_office_setup — Install or repair (or uninstall) the Office add-in.
• rebel_office_status — Check Office connection status for Word, Excel, PowerPoint.

Word (20)

• rebel_office_word_read_document — Read the active Word document body, paginated by paragraph.
• rebel_office_word_get_document_structure — Get the heading/section outline of the document.
• rebel_office_word_get_selection — Get the currently selected text and location.
• rebel_office_word_find_text — Search for text occurrences with surrounding context.
• rebel_office_word_insert_text — Insert text at a location or replace the selection (destructive).
• rebel_office_word_replace_text — Find-and-replace text in the document (destructive).
• rebel_office_word_format_text — Apply font, color, highlight, or alignment formatting (destructive).
• rebel_office_word_apply_style — Apply a named paragraph style (e.g. "Heading 1", "Quote") to existing paragraphs (destructive).
• rebel_office_word_insert_table — Insert a table with headers and rows (destructive).
• rebel_office_word_read_table — Read a table's cell values as a 2D array.
• rebel_office_word_update_table_cell — Replace the text of a sin