Excel Mcp

io.github.wesseltlPublished by GitHub account wesseltlv0.1.2Updated Oct 24, 2026

Read real, messy Excel files from an agent: multiple sheets, title rows, merged cells.

VerifiedSTDIODesktop onlyFiles & StorageData & Analytics

Overview

AI-generated overview

Local MCP server that lets an assistant read real, messy Excel workbooks — multiple sheets, title rows and merged cells — as exact, deterministic data.

What you can do
  • List every sheet in a workbook with its size
  • Preview the top rows of a sheet as a grid to see the layout
  • Read a sheet's actual data table as records, with header detection and confidence signals
  • Export a sheet's table as clean CSV text
When to use it
Useful when an assistant needs to answer questions about .xlsx files on the user's machine, especially spreadsheets that do not start cleanly at A1, have title rows above the header, or use merged cells that a pasted prompt would make the model guess at.
Requirements
Runs as a local stdio process installed from the PyPI package excel-agent-mcp (with the mcp extra) and launched with the excel-agent-mcp command; configured in an MCP client such as Claude Desktop, Cursor, VS Code/Copilot, Windsurf or Cline. No accounts or API keys are declared. Optionally set EXCEL_MCP_ALLOWED_DIR to restrict file access to one folder.
Before you install
Without EXCEL_MCP_ALLOWED_DIR the server can read any .xlsx file the process can reach, so scope it to a folder if that matters. Merged-cell values are forward-filled and therefore inferred rather than read cell by cell, and auto-detected headers can be wrong when header_confidence is low; verify results before relying on them.

Installation

In SourceWeft

  1. Open Excel Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

excel-mcp

[Python] [MCP] [License]

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 dataA2:  Generated by finance             <- note, not dataA3:  (blank)A4:  Region | Product | Units         <- the actual headerA5:  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

ToolWhat it does
list_sheets(path)Every sheet in the workbook, with its size
preview_sheet(path, sheet, rows)Top rows as a grid, so the agent can see the layout
read_table(path, sheet)The actual data table as records. Reports the decisions that could be wrong: header_source (explicit / auto-detected), header_confidence, and forward_filled_columns (values inferred from merged cells, not read)
sheet_to_csv(path, sheet)The table as clean CSV text

Getting started (Claude Desktop)

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

1. Install it

bash
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/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server:

json
{  "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 EXCEL_MCP_ALLOWED_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):

json
{ "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:

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

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

json
{ "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

read_table doesn't just return the data, it tells you how confident it is, so you can trust a clean parse and double-check a guess:

json
{  "columns": ["Region", "Product", "Revenue"],  "rows": [ ... ],  "header_row": 3,  "header_source": "auto-detected",  "header_confidence": 0.42,  "forward_filled_columns": ["Region"]}
  • header_source — "explicit" if you told it which row is the header, "auto-detected" if it guessed.
  • header_confidence — 0..1 for an auto-detected header. A low value means it was a close call; if the result looks off, pass an explicit header_row.
  • looks_clean + table_warnings — a verdict on the table as a whole (flags low header confidence, unnamed columns, mostly-empty tables), separate from the per-column signals below.
  • forward_filled_columns — columns whose values came from a merged cell. Those values are inferred (copied down to fill the block), not read cell-by-cell, so treat them accordingly.

The idea: surface the decisions that could be wrong, instead of handing back tidy-looking output that hides a guess.

Also usable from plain Python

python
from excel_mcp import reader
reader.list_sheets("report.xlsx")reader.read_table("report.xlsx", "Sales")     # {'columns': [...], 'header_source': ..., ...}reader.sheet_to_csv("report.xlsx", "Sales")

Tests

bash
python -m unittest discover -s tests     # builds its own messy xlsx, runs anywhere

License

MIT

Source: README.md at commit 87abfc9

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts