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)

xlsx-MCP