@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
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:
rebel_office_excel_set_formula β writes =B<row>*C<row> into each cell in column D.
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 <untrusted-content> 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
- A trusted local certificate for Office; your computer may ask you to approve it when it is first created or renewed
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.
To keep the add-in removed, turn off the Office connector; otherwise it is added
again the next time the connector starts.
Before you install: the state file path
The install below needs one value, MCP_OFFICE_SIDECAR_STATE, and leaves it empty. Set it to
the full path of a file named exactly sidecar-state.json, in a folder you can write to. For
example:
- Mac:
/Users/<your-username>/Library/Application Support/mcp-server-office/sidecar-state.json
- Windows:
C:\Users\<your-username>\AppData\Local\mcp-server-office\sidecar-state.json
Replace <your-username> with your own user name. Enter the path when your host asks for it,
or, in the manual config, put it in place of the empty "". Inside JSON, write each Windows
backslash twice:
"C:\\Users\\<your-username>\\AppData\\Local\\mcp-server-office\\sidecar-state.json".
Don't create the folder or the file yourself: the connector creates the folder and writes the
file when 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
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"
}
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 single table cell (destructive).
rebel_office_word_insert_image β Insert an image from a file path or base64 data (destructive).
rebel_office_word_insert_break β Insert a page or section break (destructive).
rebel_office_word_set_header_footer β Set header or footer text and alignment (destructive).
rebel_office_word_get_properties β Get document metadata (title, author, counts).
rebel_office_word_get_comments β Read comments and reply threads.
rebel_office_word_add_comment β Add a comment or threaded reply on selected text (destructive).
rebel_office_word_resolve_comment β Resolve or delete a comment by ID (destructive).
rebel_office_word_get_tracked_changes β Read tracked changes (revisions).
rebel_office_word_accept_reject_changes β Accept or reject tracked changes in bulk or by ID (destructive).
Excel (25)
rebel_office_excel_read_range β Read cell values from an A1 range or named range.
rebel_office_excel_write_range β Write a 2D array of values to a range (destructive).
rebel_office_excel_get_worksheets β List worksheets with positions and used ranges.
rebel_office_excel_add_worksheet β Add a new worksheet at a chosen position (destructive).
rebel_office_excel_delete_worksheet β Delete a worksheet and all its data (destructive).
rebel_office_excel_read_table β Read rows from a named Excel table.
rebel_office_excel_create_table β Convert a range into a named Excel table (destructive).
rebel_office_excel_set_formula β Set a formula in a cell, with optional fill-down (destructive).
rebel_office_excel_get_formulas β Read formula strings (not values) from a range.
rebel_office_excel_create_chart β Create an embedded chart from a data range (destructive).
rebel_office_excel_format_range β Apply font, fill, borders, and number formats (destructive).
rebel_office_excel_add_conditional_formatting β Add color scales, data bars, or rule-based formats (destructive).
rebel_office_excel_sort_range β Sort a range or table by one or more columns (destructive).
rebel_office_excel_filter_table β Apply or clear auto-filter on a table or range (destructive).
rebel_office_excel_get_named_ranges β List named ranges and tables in the workbook.
rebel_office_excel_insert_rows_columns β Insert rows or columns at a position (destructive).
rebel_office_excel_delete_rows_columns β Delete rows or columns and their data (destructive).
rebel_office_excel_merge_cells β Merge or unmerge cells in a range (destructive).
rebel_office_excel_auto_fit β Auto-fit column widths or row heights (destructive).
rebel_office_excel_add_data_validation β Add input validation rules to a range (destructive).
rebel_office_excel_get_comments β Read threaded cell comments.
rebel_office_excel_add_comment β Add a comment or reply on a cell (destructive).
rebel_office_excel_get_pivot_tables β List pivot tables and the worksheets they live on.
rebel_office_excel_create_pivot_table β Create a pivot table from a source range (destructive).
rebel_office_excel_refresh_pivot_table β Refresh one pivot table, or all of them.
PowerPoint (15)
rebel_office_powerpoint_get_slides β List slides with layout, title, and shape counts.
rebel_office_powerpoint_get_slide_content β Get all shapes and text on a specific slide.
rebel_office_powerpoint_add_slide β Add a new slide with a layout and optional content (destructive).
rebel_office_powerpoint_apply_layout β Change the layout of an existing slide (destructive).
rebel_office_powerpoint_delete_slide β Delete a slide by index (destructive).
rebel_office_powerpoint_reorder_slides β Move a slide to a new position (destructive).
rebel_office_powerpoint_add_text_box β Add a positioned text box to a slide (destructive).
rebel_office_powerpoint_add_image β Add an image to a slide from path or base64 (destructive).
rebel_office_powerpoint_add_shape β Add a geometric shape with optional text and fill (destructive).
rebel_office_powerpoint_delete_shape β Delete a shape from a slide by ID or name (destructive).
rebel_office_powerpoint_format_shape β Format a shape's fill, line, position, size, or name (destructive).
rebel_office_powerpoint_update_text β Update text in a shape or layout placeholder (destructive).
rebel_office_powerpoint_get_speaker_notes β Read speaker notes for one or all slides.
rebel_office_powerpoint_set_speaker_notes β Set or replace speaker notes for a slide (destructive).
rebel_office_powerpoint_get_presentation_properties β Get presentation metadata, dimensions, and layouts.
Smoke test
MCP_OFFICE_SIDECAR_STATE=/tmp/rebel-office-smoke/sidecar-state.json \
node dist/index.js
Then send a listTools MCP request on stdin; you should get back the full tool
manifest. The server does not need a live sidecar to respond to listTools.
Licence
FSL-1.1-MIT β Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.
Security
See SECURITY.md for this connector's security policy and the
repository-level SECURITY.md for vulnerability reporting.
Architecture and drift-risk notes
Sidecar lifecycle, port allocation, manifest sideloading, and the byte-compatible code vendored from the Mindstone Rebel monorepo are documented in docs/connectors/office-architecture.md. That file is the canonical reference if you are debugging the sidecar handshake or planning a release that touches the vendored sidecar/appBridge or chat code.
Action results and recovery
An action succeeds only when the requested work completes. Missing targets and
search matches return ITEM_NOT_FOUND; invalid indexes return INVALID_ARGUMENT.
Word formatting, comments and styles need selected text or an explicit target.
PowerPoint reports UNSUPPORTED_OPERATION when it cannot apply requested
formatting, text, fill or line properties. Text alignment and Excel range filter
criteria are applied, including checks for unknown filter headers before writing.
Condition filters accept named operators such as greaterThan and Excel symbols
such as >; unknown operators fail before any filter is applied. Sorting rejects
unknown table headers and resolves worksheet letters such as AA within the
requested range; exclude the header row when passing a range to sort. Unknown shape
types fail before creating a shape, and formatted shapes require PowerPointApi 1.4
before creation. Word alignment applies to every
paragraph in the target. Reading speaker notes skips the InvalidArgument
text-load error for notes-page shapes without text; other read failures return
coded errors.
Setting notes returns ITEM_NOT_FOUND when no shape name contains "notes" or "body".
Speaker-notes errors report causes such as read-only files;
unavailable layouts return a coded failure instead of an empty layout list.
If PowerPoint creates a slide but cannot finish filling it, PARTIAL
includes the created slide id in the error message. Inspect that slide, then
complete the missing work or delete it before retrying to avoid duplicates.
Find its id in get_slides and use the returned slideNumber as slideIndex
when reading or deleting it.
Setup and status cover all three apps; status tells you which apps are connected
and what to open when none are connected. To connect, click Rebel on the Home tab
(first use on Windows: Add-ins β Developer Add-ins β Rebel). When the panel says
βWaiting for Rebelβ, open Rebel on the same computer; it connects automatically.
If the connection is rejected, reconnect Microsoft Office in Rebel's Settings.