# Office MCP Server

<img src="docs/img/icon-800.png" width="128">

A Model Context Protocol (MCP) server for reading, investigating, and editing Microsoft Office files — Excel and PowerPoint. Originally forked from [excel-mcp-server](https://github.com/negokaz/excel-mcp-server) by Kazuki Negoro, this in-house fork has been substantially extended with PowerPoint support, VBA extraction, chart/defined-name/cross-sheet analysis tools, and SharePoint/OneDrive path resolution.

## Features

**Excel:**

- Read/Write text values and formulas, with pagination for large sheets
- Create, copy, and delete sheets; create Excel Tables; format cell ranges (fonts, fills, borders, number formats)
- Structural analysis: workbook triage, formula pattern fingerprinting, defined-name usage tracing, chart data extraction, error scanning, find & replace
- VBA source extraction (works even without Excel installed, by parsing `vbaProject.bin` directly)
- Resolves SharePoint/OneDrive URLs to their locally-synced file paths

**PowerPoint (🪟 Windows only):**

- List slides, describe presentation structure, read full slide content (text, tables, charts, images)
- Triage a presentation's slide roles, search text across the deck, extract speaker notes
- Export a slide as a high-quality PNG

**🪟 Windows only (all file types):**

- Live editing via Excel/PowerPoint COM automation
- Capture screen image from a sheet or slide

For more details, see the [tools](#tools) section.

## Requirements

- Go 1.23+ (to build the server binary)
- Windows is required for VBA/COM-backed tools (live editing, screen capture, PowerPoint support). Excel file reading/writing otherwise works cross-platform via [excelize](https://github.com/xuri/excelize).

## Supported file formats

**Excel:**

- xlsx (Excel book)
- xlsm (Excel macro-enabled book)
- xltx (Excel template)
- xltm (Excel macro-enabled template)
- xlsb, xls (VBA source extraction only)

**PowerPoint (Windows only):**

- pptx, pptm, ppt

## Installation

This is an internal fork, built and run from source rather than installed from a public registry.

```bash
git clone https://dev.azure.com/hymans/Market%20Solutions/_git/office-mcp
cd office-mcp
go build -o office-mcp-server.exe ./cmd/office-mcp-server
```

Then point your MCP client at the built binary:

```json
{
    "mcpServers": {
        "office": {
            "command": "C:\\path\\to\\office-mcp-server.exe",
            "env": {
                "EXCEL_MCP_PAGING_CELLS_LIMIT": "4000"
            }
        }
    }
}
```

<h2 id="tools">Tools</h2>

### `excel_describe_sheets`

Detailed per-sheet metadata: used range, Tables, PivotTables, paging ranges, and optional formula counts.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `includeFormulaCounts`
  - Count formula cells per sheet (slower). [default: false]

### `excel_list_sheet_names`

Quick inventory: sheet index, name, used-range dimensions, and any defined names, in one lightweight call.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file

### `excel_triage_workbook`

Recommended first call on any unfamiliar workbook. Rapidly maps workbook structure without reading all cells: sheet groups classified by role (config, calc_engine, raw_data, results/summary), cross-sheet dependency map, defined-name count, and recommended next tool calls.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file

### `excel_describe_workbook_full`

One-call comprehensive workbook description combining sheet inventory, structural role classification, formula-family fingerprinting, cross-sheet dependency map, defined names, chart inventory, and VBA module summary.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `includeVBASource`
  - Include full VBA module source text in the output. [default: false]

### `excel_read_sheet`

Read values from Excel sheet with pagination. Defaults: TSV output, formulas annotated (`=EXPR → value`), empty cells/rows suppressed.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `sheetName`
  - Sheet name in the Excel file
- `range`
  - Range of cells to read in the Excel sheet (e.g., "A1:C10"). [default: first paging range]
- `showFormula`
  - Show formula instead of value [default: true]
- `showStyle`
  - Show style information for cells [default: false]
- `pagingCellsLimit`
  - Override the paging cell limit for this call
- `outputFormat`
  - Output format for the returned data (e.g. TSV)
- `skipEmpty`
  - Suppress empty cells/rows in the output
- `headRows` / `tailRows`
  - Read only the first/last N rows of the range
- `useCachedValues`
  - Use last-calculated cached values instead of recalculating (useful for `#NAME?`/`#REF!` from missing add-ins)
- `namedRange`
  - Read by a defined name instead of an explicit range
- `followReferences` / `followExternalReferences`
  - Trace and inline values from formulas that reference other sheets/workbooks
- `forceRecalc`
  - Force Excel to recalculate before reading (COM backend only)

### `excel_screen_capture`

**[Windows only]** Take a screenshot of the Excel sheet with pagination. Best for summary/dashboard sheets where visual layout and conditional formatting carry meaning.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `sheetName`
  - Sheet name in the Excel file
- `range`
  - Range of cells to read in the Excel sheet (e.g., "A1:C10"). [default: first paging range]

### `excel_write_to_sheet`

Write values to the Excel sheet.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `sheetName`
  - Sheet name in the Excel file
- `newSheet`
  - Create a new sheet if true, otherwise write to the existing sheet
- `range`
  - Range of cells to read in the Excel sheet (e.g., "A1:C10").
- `values`
  - Values to write to the Excel sheet. If the value is a formula, it should start with "="

### `excel_create_table`

Create a table in the Excel sheet

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `sheetName`
  - Sheet name where the table is created
- `range`
  - Range to be a table (e.g., "A1:C10")
- `tableName`
  - Table name to be created

### `excel_copy_sheet`

Create a duplicate of an existing worksheet — for backups before editing, sandboxing formula changes, or duplicating a template sheet.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `srcSheetName`
  - Source sheet name in the Excel file
- `dstSheetName`
  - Sheet name to be copied

### `excel_delete_sheet`

Permanently delete a worksheet from an Excel workbook. This cannot be undone.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `sheetName`
  - Name of the sheet to delete

### `excel_format_range`

Format cells in the Excel sheet with style information

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `sheetName`
  - Sheet name in the Excel file
- `range`
  - Range of cells in the Excel sheet (e.g., "A1:C3")
- `styles`
  - 2D array of style objects for each cell. If a cell does not change style, use null. The number of items of the array must match the range size.
  - Style object properties:
    - `border`: Array of border styles (type, color, style)
    - `font`: Font styling (bold, italic, underline, size, strike, color, vertAlign)
    - `fill`: Fill/background styling (type, pattern, color, shading)
    - `numFmt`: Custom number format string
    - `decimalPlaces`: Number of decimal places (0-30)

### `excel_find_replace`

Find and replace text within all formulas in an Excel worksheet — useful for fixing broken references (e.g. a renamed sheet).

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `sheetName`
  - Name of the sheet to perform find & replace in
- `findText`
  - Text to search for within cell formulas
- `replaceText`
  - Text to replace matches with
- `matchCase`
  - Whether to match case when searching [default: false]

### `excel_search_formulas`

Search for a substring or regex pattern within all cell formulas (and values) in a worksheet — for structure discovery, parameter targeting, or debugging.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `sheetName`
  - Name of the sheet to search
- `query`
  - Text substring or regex pattern to search for
- `useRegex`
  - Treat query as a regular expression [default: false]
- `caseInsensitive`
  - Case-insensitive matching [default: true]
- `maxResults`
  - Maximum number of matching cells to return [default: 200]

### `excel_get_formula_patterns`

Extract the unique formula templates used in a worksheet, with row/column numbers normalised to `#` to reveal structural patterns (e.g. `=B2*C2+D2` and `=B100*C100+D100` collapse to `=B#*C#+D#`). The primary tool for understanding a sheet's structural logic before replicating it in another language.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `sheetName`
  - Sheet to analyse
- `range`
  - Restrict analysis to a specific range
- `allSheets`
  - Scan every sheet and group structurally identical sheets together [default: false]

### `excel_count_errors`

Count and locate Excel error values (`#REF!`, `#VALUE!`, `#NAME?`, `#N/A`, etc.) in a worksheet.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `sheetName`
  - Name of the sheet to scan for errors

### `excel_get_defined_names`

List all defined names (named ranges) in a workbook with their scope, formula/reference, and current resolved value.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `sheetFilter`
  - Only return names whose scope or reference contains this string (case-insensitive)
- `includeValues`
  - Inline the actual cell values for every range name [default: false]

### `excel_find_named_range_usages`

Search every sheet for cells whose formulas reference a specific defined name — trace the full blast-radius before changing a named constant's value.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `name`
  - The defined name to search for (whole-word, case-insensitive)
- `maxResults`
  - Maximum total matches to return [default: 500]

### `excel_get_chart_data`

Extract detailed information about every chart embedded in an Excel workbook — type, title, axis titles, legend, and every data series with its cell-range references. Works with .xlsx/.xlsm only.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file (.xlsx or .xlsm)
- `sheetName`
  - Only return charts on this sheet. Omit for all sheets.

### `excel_get_vba_code`

**[Windows only]** Read VBA source code from an Excel workbook (.xlsm, .xlsb, .xls) — all modules, class modules, user forms, and sheet/workbook code stubs. Works by parsing `vbaProject.bin` directly, without requiring Excel or special Trust Center settings.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the Excel file
- `module`
  - Retrieve a single named component (e.g. "Module1", "ThisWorkbook"). Omit for all modules.

### `pptx_list_slides`

**[Windows only]** Quick inventory of all slides in a PowerPoint presentation — index, title, layout type, and shape count.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the PowerPoint file (.pptx, .pptm, .ppt)

### `pptx_triage_presentation`

**[Windows only]** Recommended first call on an unfamiliar presentation. Classifies each slide by role (title, content, section_header, data, blank, image_heavy) and suggests which slides to read in detail vs capture visually.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the PowerPoint file

### `pptx_describe_presentation`

**[Windows only]** Detailed metadata: slide dimensions, total slide count, per-slide summaries with shape types, text previews, table detection, and whether speaker notes exist.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the PowerPoint file

### `pptx_read_slide`

**[Windows only]** Read the full content of a single slide — all shape text, tables as tab-separated data, chart data, pictures as base64 PNG, shape metadata, and speaker notes.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the PowerPoint file
- `slideIndex`
  - 1-based slide index

### `pptx_screen_capture`

**[Windows only]** Export a PowerPoint slide as a high-quality PNG image, for visually complex slides where layout and design matter.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the PowerPoint file
- `slideIndex`
  - 1-based slide index to capture
- `width`
  - Output image width in pixels, height auto-calculated. [default: 1280]

### `pptx_get_speaker_notes`

**[Windows only]** Extract speaker notes from one or all slides.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the PowerPoint file
- `slideIndex`
  - 1-based slide index. Omit or 0 for all slides with notes.

### `pptx_search_text`

**[Windows only]** Search for text across all slides — shape text, table content, and speaker notes.

**Arguments:**

- `fileAbsolutePath`
  - Absolute path to the PowerPoint file
- `query`
  - Text to search for
- `caseSensitive`
  - Case-sensitive search [default: false]

<h2 id="configuration">Configuration</h2>

You can change the MCP Server behaviors by the following environment variables:

### `EXCEL_MCP_PAGING_CELLS_LIMIT`

The maximum number of cells to read in a single paging operation.
[default: 4000]

### `SHAREPOINT_SYNC_MAPPINGS`

**[Windows only]** Manual overrides for mapping SharePoint/OneDrive URLs to locally-synced paths, in addition to mappings auto-discovered from the OneDrive sync engine registry.
Format: `url1|path1;url2|path2` (semicolon-separated pairs, pipe-delimited).

## License

Copyright (c) 2025 Kazuki Negoro

office-mcp-server is a fork of [excel-mcp-server](https://github.com/negokaz/excel-mcp-server), released under the [MIT License](LICENSE).