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.

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.

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