# @mindstone/mcp-server-office

[![npm version](https://img.shields.io/npm/v/@mindstone/mcp-server-office.svg)](https://www.npmjs.com/package/@mindstone/mcp-server-office)
[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](./LICENSE)

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](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-office)
- **Auth:** None ([`server.json`](./server.json))
- **Tools:** [62](./src/) (word, excel, powerpoint, setup)
- **Surface:** desktop-addin
- **Machine-readable:** [`STATUS.json`](./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):

```json
{
  "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)

<!-- BEGIN INSTALL_LINKS: do not edit by hand; regenerated by scripts/gen-install-links.mjs -->
## One-click install

[![Add to Cursor](https://img.shields.io/badge/Add_to_Cursor-black?style=for-the-badge&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=Microsoft%20Office&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtaW5kc3RvbmUvbWNwLXNlcnZlci1vZmZpY2UiXSwiZW52Ijp7Ik1DUF9PRkZJQ0VfU0lERUNBUl9TVEFURSI6IiJ9fQ)
[![Add to VS Code](https://img.shields.io/badge/Add_to_VS_Code-007ACC?style=for-the-badge&logo=visual-studio-code&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22Microsoft%20Office%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40mindstone%2Fmcp-server-office%22%5D%2C%22env%22%3A%7B%22MCP_OFFICE_SIDECAR_STATE%22%3A%22%22%7D%7D)
[![Add to VS Code Insiders](https://img.shields.io/badge/Add_to_VS_Code_Insiders-24bfa5?style=for-the-badge&logo=visual-studio-code&logoColor=white)](vscode-insiders:mcp/install?%7B%22name%22%3A%22Microsoft%20Office%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40mindstone%2Fmcp-server-office%22%5D%2C%22env%22%3A%7B%22MCP_OFFICE_SIDECAR_STATE%22%3A%22%22%7D%7D)

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

<details>
<summary>Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (Microsoft Office)</summary>

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

</details>
<!-- END INSTALL_LINKS -->

## Quick Start

### Install & build

```bash
cd <path-to-repo>/connectors/office
npm install
npm run build
```

### npx (once published)

```bash
npx -y @mindstone/mcp-server-office
```

### Local

```bash
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.

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

### Mindstone Rebel

```json
"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 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

```bash
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](./LICENSE) — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.

## Security

See [SECURITY.md](./SECURITY.md) for this connector's security policy and the
repository-level [SECURITY.md](../../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`](../../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.