Metadata-Version: 2.4
Name: excel-analytics-mcp
Version: 0.1.0
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. 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 beautiful 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

## Quick Install

```bash
bash install.sh
```

This will:
1. Check for Python 3.10+ and install `uv` if needed
2. Set up the `~/.excel-mcp/` directory
3. Install all dependencies
4. Configure Claude Desktop automatically

Then restart Claude Desktop and you're ready to go.

## How to Use

### 1. Upload Your Data

Open the dashboard at **http://localhost:8765** (available once Claude Desktop starts 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

## Dashboard

The web dashboard runs at `http://localhost:8765` and 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

## Architecture

```
Claude Desktop ←→ MCP Server (stdio) ←→ SQLite DB
                         ↓
                    REST API (port 8765) ←→ Web Dashboard
```

The MCP server communicates with Claude Desktop via stdio, while a REST API runs in a background thread to power the dashboard. Both share the same SQLite database and tool registry.

## Available Tools

### Core Tools (always available)

| Tool | Description |
|------|-------------|
| `list_datasets` | Show all loaded tables |
| `describe_dataset` | Column info, types, stats |
| `query` | Run read-only SQL queries |
| `summarize` | Statistical summary of tables/columns |

### Meta Tools (for building your toolkit)

| Tool | Description |
|------|-------------|
| `save_analysis` | Save a SQL query as a reusable 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 |

## 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, no dangerous operations.
- **Local only**: All data stored in `~/.excel-mcp/`. Nothing leaves your machine.

## File Locations

| Path | Purpose |
|------|---------|
| `~/.excel-mcp/data.db` | SQLite database with your data |
| `~/.excel-mcp/tools/` | Saved analyses and custom tools |
| `~/.excel-mcp/output/` | Tool output files |
| `~/.excel-mcp/config.json` | User configuration |

## Configuration

Edit `~/.excel-mcp/config.json`:

```json
{
  "data_dir": "~/Documents",
  "port": 8765,
  "auto_scan": false
}
```

## Development

```bash
# Install dependencies
uv sync

# Run the server directly (for testing)
uv run python -m excel_mcp
```

## License

MIT
