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_rangecaps responses at 10,000 cells and returns anext_rangecursor 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_workbookrefuses to drop unsaved changes unlessdiscard_changes=true.
Development
uv run pytest # test suite
uv run mcp dev src/excel_mcp/server.py # MCP Inspector
