@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.1.4 · npm
• Auth: None (server.json)
• Tools: 53 (word, excel, powerpoint, setup)
• Surface: desktop-addin
• Hosts tested: Claude Desktop, Cursor, Mindstone Rebel
• 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<row>*C<row> into each cell in column D.
2. rebel_office_excel_format_range — applies bold to the totals row range.

Response (trimmed):

{
  "set_formula": {
    "worksheet": "Sheet1",
    "range": "D2:D24",
    "formula": "=B2*C2",
    "filled_rows": 23
  },
  "format_range": {
    "worksheet": "Sheet1",
    "range": "A25:D25",
    "bold": true
  }
}

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)

One-click install

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

{
  "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/[email protected]"],
  "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 (53)

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 (17)

• 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_insert_table — Insert a table with headers and rows (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 (22)

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

PowerPoint (12)

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