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.

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.

Related MCP server: Excel MCP Server

Tools

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.

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:

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

// 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.

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

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