Excel MCP Server
A Model Context Protocol (MCP) server for Excel file manipulation with real-time formula calculation.
Why a Formula Engine?
Problem: Both humans and LLMs are inconsistent at math. When an AI writes =SUM(A1:A10) to a spreadsheet, it's just storing a string—the calculation never happens unless Microsoft Excel opens the file.
Solution: This MCP integrates HyperFormula, a headless spreadsheet engine that evaluates formulas in real-time. When you read a cell, you get the calculated result, not just the formula text.
write_cell(wb, "A1", 100)
write_cell(wb, "A2", 200)
write_cell(wb, "A3", "=SUM(A1:A2)")
read_cell(wb, "A3")
→ { calculatedValue: 300, formula: "=SUM(A1:A2)" }
This ensures mathematical accuracy for:
- Financial calculations
- Data aggregations
- Report generation
- Any workflow where precision matters
Features
- No Excel Required - Works with .xlsx files using pure JavaScript
- 400+ Excel Functions - SUM, AVERAGE, VLOOKUP, IF, and more via HyperFormula
- Multi-Workbook - Open and manipulate multiple workbooks simultaneously
Tools (21 total)
Workbook Management
| Tool | Description |
|---|---|
create_workbook | Create new workbook in memory, returns ID |
open_workbook | Open existing .xlsx file |
save_workbook | Save workbook to disk |
close_workbook | Close workbook and free memory |
list_workbooks | List all open workbooks |
Sheet Operations
| Tool | Description |
|---|---|
list_sheets | List all sheets in workbook |
create_sheet | Add new sheet |
delete_sheet | Remove sheet |
rename_sheet | Rename sheet |
get_sheet_info | Get dimensions and metadata |
Cell Operations
| Tool | Description |
|---|---|
read_cell | Read cell value (returns calculated result) |
write_cell | Write value or formula (prefix with =) |
read_range | Read range of cells |
write_range | Write 2D array to range |
list_columns | List columns with headers |
Formula Support
| Tool | Description |
|---|---|
get_formula | Get raw formula string from cell |
recalculate | Force recalculation of all formulas |
Charts & Pivot Tables
| Tool | Description |
|---|---|
create_chart | Create bar, line, pie, or scatter chart |
delete_chart | Remove chart |
create_pivot_table | Create pivot table from data |
Import
| Tool | Description |
|---|---|
import_markdown_table | Import markdown table to Excel |
Installation
git clone https://github.com/jauinones/excel-mcp.git
cd excel-mcp
npm install
npm run build
Configuration
Add to your Claude Code MCP settings (~/.claude.json):
{
"mcpServers": {
"excel": {
"type": "stdio",
"command": "node",
"args": ["/path/to/excel-mcp/dist/index.js"]
}
}
}
Example Usage
// Create a simple invoice
create_workbook → "wb_1"
write_cell(wb_1, "Sheet1", "A1", "Item")
write_cell(wb_1, "Sheet1", "B1", "Price")
write_cell(wb_1, "Sheet1", "C1", "Qty")
write_cell(wb_1, "Sheet1", "D1", "Total")
write_range(wb_1, "Sheet1", "A2", [
["Widget", 25.00, 10, "=B2*C2"],
["Gadget", 15.50, 20, "=B3*C3"],
["Thing", 8.99, 50, "=B4*C4"]
])
write_cell(wb_1, "Sheet1", "D5", "=SUM(D2:D4)")
read_cell(wb_1, "Sheet1", "D5")
// → { calculatedValue: 1009.5, formula: "=SUM(D2:D4)" }
save_workbook(wb_1, "/path/to/invoice.xlsx")
Tech Stack
- TypeScript - Type-safe implementation
- ExcelJS - Read/write .xlsx files
- HyperFormula - Formula calculation engine (GPLv3)
- MCP SDK - Model Context Protocol integration
License
GPLv3 (due to HyperFormula dependency)
