# Excel MCP

An MCP (Model Context Protocol) server that lets AI clients — Claude Code, GitHub Copilot CLI, VS Code Copilot, or any MCP-capable agent — read, write, and manage Excel workbooks (`.xlsx` / `.xlsm`).

No Excel installation required: workbooks are manipulated directly via [openpyxl](https://openpyxl.readthedocs.io/).

## How it works

The server is **stateful**: open a workbook once, make many edits against the in-memory copy, then save.

```
open_workbook(path)          -> session_id
write_range(session_id, "A1", [["Name","Age"],["Ana",31]])
read_range(session_id, "Sheet1!A1:B10")
save_workbook(session_id)
close_workbook(session_id)
```

Ranges use A1 notation, optionally sheet-qualified: `A1`, `A1:C10`, `Sheet1!A1:C10`, `'My Sheet'!A1:C10`.

## Tools

| Group | Tools |
|---|---|
| Workbook | `open_workbook`, `create_workbook`, `save_workbook`, `save_workbook_as`, `close_workbook`, `list_open_workbooks`, `get_workbook_info` |
| Sheets | `list_sheets`, `add_sheet`, `delete_sheet`, `rename_sheet`, `copy_sheet`, `set_active_sheet` |
| Data | `read_cell`, `write_cell`, `read_range`, `write_range`, `read_sheet`, `append_rows`, `clear_range`, `get_used_range` |
| Structure | `insert_rows`, `insert_columns`, `delete_rows`, `delete_columns` |
| Search | `find_in_workbook`, `replace_in_range` |
| Formatting | `set_font`, `set_fill_color`, `set_borders`, `set_alignment`, `set_number_format`, `set_column_width`, `set_row_height`, `auto_fit_columns`, `merge_cells`, `unmerge_cells`, `freeze_panes`, `format_as_table`, `apply_conditional_formatting`, `apply_style_preset`, `get_cell_format` |
| Formulas | `set_formula`, `fill_formula`, `get_formula`, `define_named_range`, `list_named_ranges`, `delete_named_range` |
| Analysis | `add_data_validation`, `sort_range`, `set_auto_filter`, `remove_duplicates` |
| Charts | `add_chart`, `list_charts`, `delete_chart` |
| Annotations | `add_comment`, `get_comments`, `delete_comment`, `set_hyperlink`, `remove_hyperlink` |
| Transfer | `import_csv`, `export_csv`, `export_json` |
| Images | `insert_image`, `list_images`, `delete_image` |
| Protection | `protect_sheet`, `unprotect_sheet`, `set_cell_locked` |
| Calculation | `recalculate_workbook`, `read_calculated_range` (Windows + Excel, see below) |
| Live Excel | `open_in_excel`, `export_pdf`, `run_macro` (Windows + Excel, see below) |

Formatting highlights: colors accept hex (`#FF0000`) or names (`red`, `light_blue`, `dark_blue`, ...); number formats accept aliases (`currency`, `percent`, `date`, ...) or raw Excel codes; `format_as_table` applies native Excel table styles; `apply_conditional_formatting` supports color scales, data bars, cell-value rules, and formula rules; `apply_style_preset` styles common patterns (`header`, `zebra`, `title`, `total_row`, `highlight`) in one call.

Formulas & analysis highlights: `fill_formula` adjusts relative references across a range like Excel's fill handle; `add_data_validation` builds dropdowns and numeric/date/length rules; `sort_range` and `remove_duplicates` match Excel's ordering and case-insensitive comparison.

Charts: bar, horizontal bar, line, pie, scatter, and area charts with titles, axis labels, and positioning anywhere in the workbook.

Annotations & transfer: cell comments with authors; external and internal (`#Sheet2!A1`) hyperlinks styled like Excel's; CSV import with automatic number typing; CSV/JSON export of any range or whole sheets.

Images & protection: embed png/jpg/gif/bmp pictures with proportional resizing; protect sheets (optionally with a password), unlocking chosen cells first with `set_cell_locked`.

Excel bridge (Windows + Microsoft Excel, `uv sync --extra com`): `recalculate_workbook` drives a hidden Excel instance to compute formulas and cache the results, then `read_calculated_range` returns computed values instead of formula text; `export_pdf` prints a sheet or workbook to PDF; `open_in_excel` pops the file open in a visible window for the user; `run_macro` executes VBA in `.xlsm` files and reloads the session with the macro's changes. On machines without Excel these tools return setup guidance instead of failing silently.

Roadmap: pivot tables, workbook-level protection, richer chart styling.

## Setup

Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).

```sh
git clone <this-repo>
cd Excel-MCP
uv sync                 # add --extra com on Windows for the Excel bridge
```

Then register the server with your client. Quick versions:

```sh
# Claude Code (add --scope user to make it global)
claude mcp add excel -- uv --directory C:/path/to/Excel-MCP run excel-mcp
```

```json
// VS Code GitHub Copilot: .vscode/mcp.json (workspace) or user mcp.json (global)
{
  "servers": {
    "excel": {
      "command": "uv",
      "args": ["--directory", "C:/path/to/Excel-MCP", "run", "excel-mcp"]
    }
  }
}
```

For GitHub Copilot CLI, global installs, installing the server as a standalone `excel-mcp` command, and troubleshooting, see **[CLIENT_SETUP.md](CLIENT_SETUP.md)**.

## Notes & limitations

- Formulas are **stored, not calculated** by the file engine — openpyxl writes formula text; Excel evaluates it on next open. Use `recalculate_workbook` (Windows + Excel) to compute results on demand.
- `read_range` caps responses at 10,000 cells and returns a `next_range` cursor for paging through big sheets; per-cell edits (formatting, clearing, replacing) are capped at 100,000 cells.
- Charts created by this server round-trip through save/load. Workbooks authored in Excel may carry chart formatting details that openpyxl simplifies on resave.
- `close_workbook` refuses to drop unsaved changes unless `discard_changes=true`.

## Development

```sh
uv run pytest          # test suite
uv run mcp dev src/excel_mcp/server.py   # MCP Inspector
```