Metadata-Version: 2.4
Name: excel-analytics-mcp
Version: 0.1.3
Summary: Self-evolving Excel analytics toolkit — MCP server + dashboard for Claude Desktop
Project-URL: Homepage, https://github.com/blakethom8/excel-mcp
Project-URL: Repository, https://github.com/blakethom8/excel-mcp
Author: Blake Thomson
License: MIT
Keywords: analytics,claude,excel,llm,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.115.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=2.1.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: tabulate>=0.9.0
Requires-Dist: uvicorn[standard]>=0.30.0
Description-Content-Type: text/markdown

# 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
