{
  "markdown": "<!-- mcp-name: io.github.wesseltl/excel-mcp -->\n\n# excel-mcp\n\n![Python](https://img.shields.io/badge/python-3.10%2B-blue)\n![MCP](https://img.shields.io/badge/MCP-server-6E56CF)\n![License](https://img.shields.io/badge/license-MIT-green)\n\n**Let your AI agent read real, messy Excel files.** An [MCP](https://modelcontextprotocol.io) server\nthat handles the things LLMs choke on: multiple sheets, title rows sitting above the actual table, and\nmerged cells.\n\nIf you paste a spreadsheet into a prompt, the model has to guess where the data starts and what the\nmerged cells mean, and it often gets it wrong. This reads the file properly with deterministic code, so\nthe values are exact and the model never invents cell contents.\n\n## The problem it solves\n\nA real spreadsheet almost never starts cleanly at cell A1:\n\n```\nA1:  Quarterly Sales Report 2024      <- title, not data\nA2:  Generated by finance             <- note, not data\nA3:  (blank)\nA4:  Region | Product | Units         <- the actual header\nA5:  North  | Widget  | 120\n...\n```\n\nAsk an LLM to read that and it'll often treat the title as a column. `read_table` auto-detects that\nthe header is on row 4 and returns clean records. Merged cells (a value spanning several rows) get\nforward-filled, so rows don't lose their category.\n\n## The tools it gives an agent\n\n| Tool | What it does |\n|---|---|\n| `list_sheets(path)` | Every sheet in the workbook, with its size |\n| `preview_sheet(path, sheet, rows)` | Top rows as a grid, so the agent can see the layout |\n| `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) |\n| `sheet_to_csv(path, sheet)` | The table as clean CSV text |\n\n## Getting started (Claude Desktop)\n\nThe fastest way to use this is with an MCP client like Claude Desktop. Three steps:\n\n**1. Install it**\n\n```bash\npip install \"excel-agent-mcp[mcp]\"\n```\n\n**2. Add it to your client's config**\n\nClaude Desktop's config lives here:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nAdd the server:\n\n```json\n{\n  \"mcpServers\": {\n    \"excel\": { \"command\": \"excel-agent-mcp\" }\n  }\n}\n```\n\n**3. Restart Claude Desktop.** You'll see a tools icon appear, meaning the server is connected.\n\nThat's it. Now ask about any `.xlsx` file on your machine:\n\n```\nYou:  What's in /Users/me/reports/sales.xlsx?\n\nAgent (calls list_sheets, then read_table):\n  The workbook has one sheet, \"Q1\". The table starts on row 4 (the rows above\n  are a title). 3 rows: North/Widget/2400, South/Widget/3000, South/Gadget/2400.\n  Total revenue 7800.\n```\n\nThe agent reads the real file instead of guessing, so the numbers are exact.\n\n> **Restricting file access:** to stop the agent reading anything outside one folder, set\n> `EXCEL_MCP_ALLOWED_DIR`. See [SECURITY.md](SECURITY.md).\n\n## Use it with other MCP clients\n\nThe same server works in any MCP client, only the config differs. Use `excel-agent-mcp` as the command.\n\n**Cursor** — `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project). Same shape as Claude\nDesktop, and it hot-reloads (no restart):\n\n```json\n{ \"mcpServers\": { \"excel\": { \"command\": \"excel-agent-mcp\" } } }\n```\n\n**VS Code / GitHub Copilot** — `.vscode/mcp.json`. Note the different key (`servers`, not `mcpServers`)\nand the required `type`. Tools only run in Copilot **Agent mode**:\n\n```json\n{ \"servers\": { \"excel\": { \"type\": \"stdio\", \"command\": \"excel-agent-mcp\" } } }\n```\n\n**Windsurf** — `~/.codeium/windsurf/mcp_config.json` (create it if missing). Same shape as Claude\nDesktop:\n\n```json\n{ \"mcpServers\": { \"excel\": { \"command\": \"excel-agent-mcp\" } } }\n```\n\n**Cline** — add it from the extension's MCP settings panel in VS Code (command: `excel-agent-mcp`).\n\n## Understanding the output\n\n`read_table` doesn't just return the data, it tells you how confident it is, so you can trust a clean\nparse and double-check a guess:\n\n```json\n{\n  \"columns\": [\"Region\", \"Product\", \"Revenue\"],\n  \"rows\": [ ... ],\n  \"header_row\": 3,\n  \"header_source\": \"auto-detected\",\n  \"header_confidence\": 0.42,\n  \"forward_filled_columns\": [\"Region\"]\n}\n```\n\n- **`header_source`** — `\"explicit\"` if you told it which row is the header, `\"auto-detected\"` if it\n  guessed.\n- **`header_confidence`** — `0..1` for an auto-detected header. A low value means it was a close call;\n  if the result looks off, pass an explicit `header_row`.\n- **`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.\n- **`forward_filled_columns`** — columns whose values came from a merged cell. Those values are\n  *inferred* (copied down to fill the block), not read cell-by-cell, so treat them accordingly.\n\nThe idea: surface the decisions that could be wrong, instead of handing back tidy-looking output that\nhides a guess.\n\n## Also usable from plain Python\n\n```python\nfrom excel_mcp import reader\n\nreader.list_sheets(\"report.xlsx\")\nreader.read_table(\"report.xlsx\", \"Sales\")     # {'columns': [...], 'header_source': ..., ...}\nreader.sheet_to_csv(\"report.xlsx\", \"Sales\")\n```\n\n## Tests\n\n```bash\npython -m unittest discover -s tests     # builds its own messy xlsx, runs anywhere\n```\n\n## License\n\nMIT\n",
  "bytes": 5418,
  "sha": "f41d6a665debefc5840aa32230e8f8593dbc88fd4d644340a81d2b4266618948",
  "repo_slug": "wesseltl/excel-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wesseltl_excel_mcp_3337f774/readme"
}