Excel MCP server

<!-- mcp-name: io.github.wesseltl/excel-mcp -->

excel-mcp

Let your AI agent read real, messy Excel files. An MCP server that handles the things LLMs choke on: multiple sheets, title rows sitting above the actual table, and merged cells.

If you paste a spreadsheet into a prompt, the model has to guess where the data starts and what the merged cells mean, and it often gets it wrong. This reads the file properly with deterministic code, so the values are exact and the model never invents cell contents.

The problem it solves

A real spreadsheet almost never starts cleanly at cell A1:

A1:  Quarterly Sales Report 2024      <- title, not data
A2:  Generated by finance             <- note, not data
A3:  (blank)
A4:  Region | Product | Units         <- the actual header
A5:  North  | Widget  | 120
...

Ask an LLM to read that and it'll often treat the title as a column. read_table auto-detects that the header is on row 4 and returns clean records. Merged cells (a value spanning several rows) get forward-filled, so rows don't lose their category.

The tools it gives an agent

Getting started (Claude Desktop)

The fastest way to use this is with an MCP client like Claude Desktop. Three steps:

1. Install it

pip install "excel-agent-mcp[mcp]"

2. Add it to your client's config

Claude Desktop's config lives here:

• macOS: ~/Library/Application Support/Claude/claudedesktopconfig.json
• Windows: %APPDATA%\Claude\claudedesktopconfig.json

Add the server:

{
  "mcpServers": {
    "excel": { "command": "excel-agent-mcp" }
  }
}

3. Restart Claude Desktop. You'll see a tools icon appear, meaning the server is connected.

That's it. Now ask about any .xlsx file on your machine:

You:  What's in /Users/me/reports/sales.xlsx?

Agent (calls list_sheets, then read_table):
  The workbook has one sheet, "Q1". The table starts on row 4 (the rows above
  are a title). 3 rows: North/Widget/2400, South/Widget/3000, South/Gadget/2400.
  Total revenue 7800.

The agent reads the real file instead of guessing, so the numbers are exact.

Restricting file access: to stop the agent reading anything outside one folder, set

EXCELMCPALLOWED_DIR. See SECURITY.md.

Use it with other MCP clients

The same server works in any MCP client, only the config differs. Use excel-agent-mcp as the command.

Cursor — ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project). Same shape as Claude Desktop, and it hot-reloads (no restart):

{ "mcpServers": { "excel": { "command": "excel-agent-mcp" } } }

VS Code / GitHub Copilot — .vscode/mcp.json. Note the different key (servers, not mcpServers) and the required type. Tools only run in Copilot Agent mode:

{ "servers": { "excel": { "type": "stdio", "command": "excel-agent-mcp" } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json (create it if missing). Same shape as Claude Desktop:

{ "mcpServers": { "excel": { "command": "excel-agent-mcp" } } }

Cline — add it from the extension's MCP settings panel in VS Code (command: excel-agent-mcp).

Understanding the output

Shortened. The full README is on GitHub.