excel-mcp-server

Local Model Context Protocol (MCP) server that lets LLMs explore Excel workbooks. It combines:

• ExcelJS — parses .xlsx / .xlsm files (values, formulas, rich text, hyperlinks, dates).
• HyperFormula — an in-memory spreadsheet engine that re-evaluates every formula, so tools return the computed result rather than the value cached in the file.

The server speaks MCP over stdio, so it works with any MCP-compatible client: VS Code, Claude Desktop, Cursor, and custom agents.

License: GPL-3.0-or-later. HyperFormula is dual-licensed (GPL-3.0 or commercial); see NOTICE for details.

---

Intended use

This repository is a personal, educational proof-of-concept. Please read this section before reusing the code.

Do not:

• Bundle this project inside a commercial software product.
• Deploy this project as part of a paid SaaS offering.
• Redistribute this project (or its binaries) under any license other than GPL-3.0-or-later.
• Use this project as a substitute for a properly licensed HyperFormula commercial integration.

Why the caveat? HyperFormula (see the Credits section below) is dual-licensed. This project uses the open-source GPL-3.0 tier by passing licenseKey: 'gpl-v3' at engine construction. If you plan to embed HyperFormula in commercial or closed-source software, you must obtain a commercial license directly from Handsontable and use your commercial license key. Doing so is a requirement of HyperFormula's dual-licensing model, not a limitation of this repository.

Everything else in this repository (ExcelJS, MCP SDK, Zod, TypeScript, etc.) is MIT / Apache-2.0 licensed and free to reuse under those terms.

If your use case is purely personal exploration, learning, or open-source contribution back to a GPL-3.0-or-later project, you are welcome to use, fork, and modify this code freely.

---

How this was built

This repository was scaffolded and iterated on with the help of an AI coding assistant (Anthropic's Claude, via GitHub Copilot's agent mode in VS Code). The design decisions, dependency choices, licensing posture, and architectural trade-offs were driven by the author; the assistant contributed code generation, test scaffolding, and documentation drafting under human review. All committed code has been read and vetted by a human before landing.

---

Features

The server exposes 10 read-only tools that cover the common "explore this spreadsheet" workflow:

Tool	Purpose
open_workbook	Load a local .xlsx/.xlsm file and get back a workbookId.
list_workbooks	List all workbooks currently loaded in the session.
list_sheets	Enumerate sheets with row/column counts.
get_sheet_summary	Dimensions, header row heuristic, per-column type inference, sample.
read_range	Read a rectangular A1 range with computed values and optional formulas.
get_cell	Value + formula + cell type + number format for a single cell.
evaluate_formula	Evaluate an arbitrary Excel formula against the loaded workbook.
find_in_workbook	Substring / regex search across all sheets (values and formulas).
get_workbook_stats	Aggregate counts (non-empty, formulas, errors) per sheet and overall.
close_workbook	Release memory held by a workbook.

Highlights:

• Formulas are re-evaluated by HyperFormula — you always see the live computed value, never a stale cached one.
• Handles cross-sheet references (=SUM(Data!C2:C5)), named expressions defined in the file, and standard Excel error types (#DIV/0!, #N/A, …).
• Safe by default: read-only, size- and cell-count-capped, and an optional allow-list restricts which directories can be opened.
• No writes, no network calls, no telemetry.

---

Install & run

Prerequisites: Node.js ≥ 18.17 (Node 20+ recommended).

git clone https://github.com/manil2020/excel_mcp_server.git
cd excel_mcp_server
npm install
npm run build
npm test        # runs the vitest suite

# Start the server on stdio (this is what MCP clients do automatically)
node dist/index.js

For local development without a build step:

npm run dev

---

Wiring the server into MCP clients

VS Code (GitHub Copilot Chat MCP)

Add the server to your workspace or user MCP config. A minimal .vscode/mcp.json:

{
  "servers": {
    "excel": {
      "command": "node",
      "args": ["/absolute/path/to/excel_mcp_server/dist/index.js"],
      "env": {
        "EXCEL_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

See examples/vscode-mcp.json for a ready-to-copy version.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on Windows / Linux:

{
  "mcpServers": {
    "excel": {
      "command": "node",
      "args": ["/absolute/path/to/excel_mcp_server/dist/index.js"]
    }
  }
}

See examples/claude-desktop-config.json.

Any other MCP client

Point the client at node /absolute/path/to/dist/index.js with the environment variables described below. The server uses stdio, the standard MCP local transport.

---

Configuration

All configuration is via environment variables. Defaults are safe for a laptop workload.

Variable	Default	Description
EXCEL_MCP_MAX_FILE_MB	100	Reject workbooks larger than this many megabytes.
EXCEL_MCP_MAX_WORKBOOKS	8	Maximum number of workbooks kept in memory concurrently.
EXCEL_MCP_ALLOWED_ROOTS	(unset)	Colon-separated absolute paths. If set, only files under one of these roots may be opened.
EXCEL_MCP_LOG_LEVEL	info	debug / info / warn / error. Logs go to stderr as JSON lines.

---

Example workflow (LLM-side)

open_workbook(path="/data/orders.xlsx")
→ { workbookId: "wb_a1b2c3d4", sheets: [ ... ] }

get_sheet_summary(workbookId, sheet="Orders")
→ headers: ["order_id", "customer", "amount", "region"], columnTypes: [ ... ]

find_in_workbook(workbookId, query="EMEA")
→ hits: [ { sheet: "Orders", cell: "D42", value: "EMEA" }, ... ]

evaluate_formula(workbookId, formula="=SUMIFS(Orders!C:C, Orders!D:D, \"EMEA\")")
→ { result: 12345.67 }

close_workbook(workbookId)

---

Architecture

• src/index.ts – Bin entry: creates the server and connects a StdioServerTransport.
• src/server.ts – Constructs McpServer, wires all tools, exports createServer() for tests.
• src/workbook/loader.ts – Reads the file with ExcelJS, converts each cell into HyperFormula-friendly primitives (formulas kept as =… strings, dates converted to Excel serial numbers, rich text flattened), then calls HyperFormula.buildFromSheets.
• src/workbook/manager.ts – Registry of open workbooks keyed by opaque wb_* handles, with per-process limits and graceful shutdown.
• src/tools/*.ts – One file per MCP tool. Each registers itself with the shared McpServer and delegates to the workbook manager.

See docs/ARCHITECTURE.md for a diagram and the full data flow.

---

Development

npm run dev          # tsx watch (single run)
npm run typecheck    # tsc --noEmit
npm run lint         # eslint
npm run format       # prettier --write
npm test             # vitest run
npm run test:watch   # vitest watch

Directory layout:

excel_mcp_server/
├── src/
│   ├── index.ts              # #!/usr/bin/env node entry
│   ├── server.ts             # MCP server factory
│   ├── workbook/             # ExcelJS + HyperFormula bridge
│   ├── tools/                # One file per MCP tool
│   └── util/                 # Address helpers, errors, logger, path safety
├── tests/
│   ├── fixtures/             # Programmatic xlsx generation
│   ├── loader.test.ts        # Workbook layer
│   └── tools.test.ts         # Full MCP round-trip (in-memory transport)
├── docs/
│   ├── ARCHITECTURE.md
│   └── USAGE.md
├── examples/
│   ├── vscode-mcp.json
│   └── claude-desktop-config.json
├── LICENSE                   # GPL-3.0
└── NOTICE                    # Third-party licensing

---

Licensing summary

This project uses HyperFormula, which is dual-licensed under GPL-3.0 or a commercial license from Handsontable. Because this project links against HyperFormula, the combined work is distributed as GPL-3.0-or-later. See NOTICE for full detail and instructions for commercial reuse.

The other runtime dependencies (ExcelJS, @modelcontextprotocol/sdk, zod) are MIT-licensed and compatible with GPL-3.0.

---

Credits & acknowledgements

This project would not exist without the following open-source libraries and the maintainers who built them. If you find this project useful, please star and support the upstream projects — they did the hard work.

Runtime dependencies

Project	Maintainer(s)	License	Homepage
HyperFormula	Handsontable Sp. z o.o. (Poland)	GPL-3.0 / Commercial	hyperformula.handsontable.com · source
ExcelJS	Guyon Roche and contributors	MIT	github.com/exceljs/exceljs
@modelcontextprotocol/sdk	Anthropic PBC and the MCP community	MIT	github.com/modelcontextprotocol/typescript-sdk
zod	Colin McDonnell (@colinhacks) and contributors	MIT	zod.dev

Development dependencies

Project	Maintainer(s)	License
TypeScript	Microsoft	Apache-2.0
Vitest	Anthony Fu (@antfu) and contributors	MIT
tsx	Hiroki Osame (@privatenumber)	MIT
ESLint	OpenJS Foundation / ESLint team	MIT
Prettier	Prettier team	MIT
Node.js	OpenJS Foundation	MIT

Protocol

The Model Context Protocol specification is developed and stewarded by Anthropic and the wider MCP community at modelcontextprotocol.io. The protocol design work makes servers like this one possible.

Sample data

• The samples/financial-sample.xlsx fixture (used for local testing only, gitignored) is Microsoft's public Power BI Financial Sample workbook, freely distributed by Microsoft for learning purposes: download link.
• All other files in samples/ are synthesised locally by scripts/generate-samples.ts and contain no real personal or commercial data.

If any maintainer name or attribution detail here is missing or wrong, please open an issue — corrections are welcome and I want the credit right.

---

Roadmap

• Optional write tools (set_cell, save_workbook) behind an opt-in --allow-writes flag.
• Streaming for very large ranges via read_range pagination.
• CSV / .xls legacy format support.
• Prompt / resource providers exposing the workbook as MCP Resources.