# Excel Analytics MCP Server
A self-evolving data analytics toolkit for [Claude Desktop](https://claude.ai/download). Drop your Excel files in, ask questions in plain English, and build up a personal library of reusable analysis tools — no coding required.
## What It Does
- **Upload Excel/CSV files** via a web dashboard
- **Ask Claude** questions about your data in natural language
- **Save analyses** as reusable tools you can run again and again
- **Create custom tools** that Claude can use on your behalf
- **Everything stays local** — your data never leaves your machine
## Install
### Option 1: PyPI (recommended)
Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/getting-started/installation/).
```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install and configure Claude Desktop
uvx excel-analytics-mcp --setup
```
That's it. Restart Claude Desktop and start asking questions.
### Option 2: From source
```bash
git clone https://github.com/blakethom8/excel-mcp.git
cd excel-mcp
bash install.sh
```
The install script will:
1. Check for Python 3.10+ and install `uv` if needed
2. Install all dependencies in an isolated virtual environment
3. Configure Claude Desktop automatically
4. Create the data directory at `~/Documents/Excel Analytics/`
## How to Use
### 1. Upload Your Data
Open the dashboard at **http://localhost:8765** (starts automatically when Claude Desktop launches the server) and drag your Excel or CSV files into the upload zone.
### 2. Ask Claude Questions
In Claude Desktop, try prompts like:
- *"What datasets do I have?"*
- *"Describe the sales table"*
- *"Show me the top 10 customers by revenue"*
- *"What's the average order value by month?"*
- *"Find all invoices over $5,000 from last week"*
### 3. Save Reusable Analyses
When you find a useful query, ask Claude to save it:
- *"Save this as a tool called 'Top Customers'"*
- *"Create a reusable analysis for monthly revenue trends"*
### 4. Manage Your Tools
Visit the **Tools** tab in the dashboard to:
- View all your saved analyses and custom tools
- Edit tool parameters
- Test tools with different inputs
- Delete tools you no longer need
## How It Works
```
Claude Desktop ←→ MCP Server (stdio) ←→ SQLite DB
↓
REST API (port 8765) ←→ Web Dashboard
```
- **MCP Server** communicates with Claude Desktop via stdio (the [Model Context Protocol](https://modelcontextprotocol.io/))
- **REST API** runs in a background thread on `localhost:8765` to power the dashboard
- **SQLite** stores your data locally — Excel/CSV files are converted on upload
- Both the MCP server and dashboard share the same database and tool registry
### Data Ingestion
When you upload an Excel file:
1. Each sheet becomes a separate SQLite table
2. Column names are cleaned (lowercase, underscores)
3. Numeric columns are auto-detected and properly typed
4. Headers are auto-detected (no manual configuration needed)
## Available Tools
### Core Tools (always available)
| Tool | Description |
|------|-------------|
| `list_datasets` | Show all loaded tables with row/column counts |
| `describe_dataset` | Column names, types, sample values, and basic stats |
| `query` | Run read-only SQL queries against your data |
| `summarize` | Statistical summary of a table or specific column |
### Meta Tools (for building your toolkit)
| Tool | Description |
|------|-------------|
| `save_analysis` | Save a SQL query as a reusable named tool |
| `create_tool` | Build a custom Python tool (sandboxed) |
| `list_my_tools` | See all your saved tools |
| `edit_tool` | Update an existing tool |
| `delete_tool` | Remove a tool |
| `test_tool` | Run a tool with test parameters |
### Dynamic Tools
Tools you create (via Claude or the dashboard) are saved as JSON files and automatically registered as MCP tools on startup. They persist across sessions and can be shared.
## Dashboard
The web dashboard at `http://localhost:8765` provides:
- **Data Manager** — upload files, browse tables, preview data, see column stats
- **Tool Workshop** — view core tools, manage saved analyses, test tools with auto-generated forms
The dashboard is a single HTML file with no build step — it works in any modern browser.
## Where Your Data Lives
All data stays on your machine in a visible, browsable folder:
| Path | Purpose |
|------|---------|
| `~/Documents/Excel Analytics/data.db` | SQLite database with all your uploaded data |
| `~/Documents/Excel Analytics/tools/` | Saved analyses and custom tools (JSON files) |
| `~/Documents/Excel Analytics/output/` | Generated output files |
| `~/Documents/Excel Analytics/config.json` | User configuration |
You can override the base directory with the `EXCEL_MCP_HOME` environment variable.
## Security
- **SQL**: Read-only queries only (`SELECT`). No writes, drops, or schema changes.
- **Python tools**: Sandboxed execution with restricted imports. No file system access, no network calls, no dangerous operations.
- **Local only**: All data stored in `~/Documents/Excel Analytics/`. Nothing is sent to external servers. The MCP server communicates only with Claude Desktop on your machine.
- **No telemetry**: No usage tracking, no analytics, no phone-home.
## Configuration
Edit `~/Documents/Excel Analytics/config.json`:
```json
{
"port": 8765,
"auto_scan": false
}
```
| Setting | Default | Description |
|---------|---------|-------------|
| `port` | `8765` | Dashboard port |
| `auto_scan` | `false` | Auto-scan a directory for Excel files on startup |
## Development
```bash
git clone https://github.com/blakethom8/excel-mcp.git
cd excel-mcp
uv sync
uv run python -m excel_mcp
```
## Requirements
- Python 3.10+
- [Claude Desktop](https://claude.ai/download)
- macOS, Windows, or Linux
## License
MIT
