Metadata-Version: 2.4
Name: excel-agent-mcp
Version: 0.1.1
Summary: An MCP server that lets AI agents read real, messy Excel files: multiple sheets, title rows, merged cells.
Author: Wessel ter Laak
License: MIT
Project-URL: Homepage, https://github.com/wesseltl/excel-mcp
Keywords: mcp,ai-agents,excel,xlsx,spreadsheet,data-extraction,llm,model-context-protocol
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: openpyxl>=3.1
Provides-Extra: mcp
Requires-Dist: fastmcp>=2.0; extra == "mcp"
Dynamic: license-file

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

# excel-mcp

![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![MCP](https://img.shields.io/badge/MCP-server-6E56CF)
![License](https://img.shields.io/badge/license-MIT-green)

**Let your AI agent read real, messy Excel files.** An [MCP](https://modelcontextprotocol.io) 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

| Tool | What 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 (auto-detects the header row) |
| `sheet_to_csv(path, sheet)` | The table as clean CSV text |

## Quickstart

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

Add it to your MCP client (e.g. Claude Desktop):

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

Now your agent can answer "what's in this spreadsheet?" or "pull the sales table out of sheet 2" by
reading the file, not guessing.

## Also usable from plain Python

```python
from excel_mcp import reader

reader.list_sheets("report.xlsx")
reader.read_table("report.xlsx", "Sales")     # {'columns': [...], 'rows': [...], 'header_row': 3}
reader.sheet_to_csv("report.xlsx", "Sales")
```

## Tests

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

## License

MIT
