excel-analytics-mcp 0.1.0__tar.gz

excel_analytics_mcp-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# uv
+uv.lock
+
+# Data (user data stays local)
+*.db
+*.sqlite
+
+# Test artifacts
+.pytest_cache/
+.coverage
+htmlcov/
+
+# User config (generated at install time)
+config.json

excel_analytics_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+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

excel_analytics_mcp-0.1.0/README.md

@@ -0,0 +1,136 @@
+# 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

excel_analytics_mcp-0.1.0/SPEC.md

@@ -0,0 +1,256 @@
+# Excel MCP Server — Product Spec
+
+## Vision
+A self-evolving data analytics toolkit for non-technical users. Users drop Excel files into a dashboard, ask Claude questions in plain English, and build up a personalized library of reusable analysis tools — all without writing code.
+
+## Target User
+- Non-technical professional (e.g. "Dave")
+- Has Excel files they analyze regularly
+- Has Claude Desktop installed
+- Comfortable dragging files and talking to AI
+- Does NOT want to: write code, edit config files, use terminal
+
+## Architecture
+
+```
+Claude Desktop (MCP Client)
+    ↓ stdio
+MCP Server (Python, FastMCP)
+    ↓ shared state
+SQLite DB (~/.excel-mcp/data.db)     — ingested Excel data
+Tool Registry (~/.excel-mcp/tools/)  — saved analyses & custom tools
+    ↓ REST API
+Frontend (localhost:8765)            — dashboard for data + tool management
+```
+
+## Core Components
+
+### 1. MCP Server (FastMCP, stdio transport)
+
+**Core Tools (always available, not editable):**
+
+| Tool | Purpose |
+|------|---------|
+| `list_datasets` | Show all loaded tables with row/column counts |
+| `describe_dataset` | Column names, types, sample values, basic stats for a table |
+| `query` | Run any read-only SQL against the SQLite DB |
+| `summarize` | Quick statistical summary of a table or column |
+
+**Meta Tools (for creating/managing user tools):**
+
+| Tool | Purpose |
+|------|---------|
+| `save_analysis` | Save a SQL template as a reusable named tool |
+| `create_tool` | Create a custom Python tool (sandboxed) |
+| `list_my_tools` | Show all user-created tools |
+| `edit_tool` | Update an existing saved analysis or custom tool |
+| `delete_tool` | Remove a user-created tool |
+| `test_tool` | Run a tool with given parameters and return results |
+
+**Dynamic Tools:**
+- On startup, server reads `~/.excel-mcp/tools/` directory
+- Each JSON file becomes a registered MCP tool
+- Saved analyses = SQL templates with parameter substitution
+- Custom tools = sandboxed Python functions
+
+### 2. Frontend (Single-page dashboard, localhost:8765)
+
+**Tech:** Single HTML file served by FastAPI. Vanilla JS + minimal CSS (Pico CSS or similar). No build step, no npm.
+
+**Pages/Sections:**
+
+**Data Manager:**
+- Drag-and-drop upload zone for Excel/CSV files
+- Table list: name, source file, rows, columns, last updated
+- Click table → preview (first 50 rows), column info, basic stats
+- Delete table button
+- Re-upload / refresh button
+
+**Tool Workshop:**
+- Three sections: Core Tools (read-only), Saved Analyses (editable), Custom Tools (editable)
+- Each tool shows: name, description, parameter schema, created date
+- Actions per tool: Edit, Delete, Test
+- Test UI: auto-generated form from parameter schema → run → show results
+- "Create New" button (opens a form for saved analysis creation)
+- Saved analyses show the SQL template
+- Custom tools have "View Code" toggle
+
+**Activity Log (nice-to-have):**
+- Recent queries and tool runs
+- Helps Dave see what Claude has been doing
+
+### 3. Data Ingestion
+
+**Excel Ingest Flow:**
+1. User drops file (via frontend upload or configured DATA_DIR scan)
+2. Parse with openpyxl/pandas
+3. Header detection: use first row with >60% non-null values as headers
+4. Clean column names: strip whitespace, lowercase, spaces → underscores
+5. Each sheet → separate SQLite table named `{filename}__{sheet_name}`
+6. Store metadata in `_meta` table (source file, sheet, ingest time, row count)
+7. If table already exists, replace it (re-upload = refresh)
+
+**Supported formats:** .xlsx, .xls, .csv
+
+### 4. Tool Registry
+
+**Storage:** `~/.excel-mcp/tools/` directory, one JSON file per tool.
+
+**Saved Analysis schema:**
+```json
+{
+  "id": "big_invoices_last_week",
+  "type": "saved_analysis",
+  "name": "Big Invoices Last Week",
+  "description": "Show invoices over a threshold from the past 7 days",
+  "created_at": "2026-02-12T17:00:00Z",
+  "updated_at": "2026-02-12T17:00:00Z",
+  "sql_template": "SELECT * FROM {table} WHERE amount > :min_amount AND date >= date('now', '-7 days')",
+  "parameters": {
+    "table": {"type": "string", "description": "Table to query", "required": true},
+    "min_amount": {"type": "number", "description": "Minimum invoice amount", "default": 5000}
+  }
+}
+```
+
+**Custom Tool schema:**
+```json
+{
+  "id": "flag_duplicate_invoices",
+  "type": "custom_tool",
+  "name": "Flag Duplicate Invoices",
+  "description": "Find potential duplicate invoices (same client, amount, within N days)",
+  "created_at": "2026-02-12T17:00:00Z",
+  "updated_at": "2026-02-12T17:00:00Z",
+  "python_code": "def run(db, client_col='client', amount_col='amount', date_col='date', days=3):\n    ...",
+  "parameters": {
+    "table": {"type": "string", "required": true},
+    "days": {"type": "integer", "default": 3, "description": "Days proximity threshold"}
+  }
+}
+```
+
+### 5. Security & Sandboxing
+
+**SQL queries:**
+- Read-only (SELECT only, block INSERT/UPDATE/DELETE/DROP/ALTER)
+- Timeout: 10 seconds
+- Max rows: 10,000
+
+**Custom Python tools:**
+- Allowed imports: pandas, numpy, datetime, json, math, statistics, re, collections
+- Blocked: os, subprocess, shutil, pathlib, sys, importlib, eval, exec, __import__
+- No file writes outside `~/.excel-mcp/output/`
+- No network access
+- Execution timeout: 30 seconds
+
+### 6. Installation
+
+**install.sh script:**
+1. Check for Python 3.10+ (guide to install if missing)
+2. Check for `uv` (install if missing)
+3. Create `~/.excel-mcp/` directory structure
+4. Clone/download the project
+5. Create virtualenv, install dependencies
+6. Detect Claude Desktop config location (macOS vs other)
+7. Inject MCP server config into `claude_desktop_config.json`
+8. Optionally set DATA_DIR if user provides a path
+9. Print success message with next steps
+
+**Claude Desktop config injection:**
+```json
+{
+  "mcpServers": {
+    "excel-analytics": {
+      "command": "uv",
+      "args": ["run", "--directory", "~/.excel-mcp/excel-mcp", "python", "-m", "excel_mcp"],
+      "env": {
+        "DATA_DIR": "~/Documents"
+      }
+    }
+  }
+}
+```
+
+## Directory Structure
+
+```
+excel-mcp/
+├── pyproject.toml
+├── README.md
+├── LICENSE (MIT)
+├── install.sh
+├── excel_mcp/
+│   ├── __init__.py
+│   ├── __main__.py              # Entry point
+│   ├── server.py                # FastMCP server + FastAPI app
+│   ├── config.py                # Paths, constants, settings
+│   ├── database.py              # SQLite connection, query execution
+│   ├── ingest.py                # Excel/CSV parsing and loading
+│   ├── tools/
+│   │   ├── __init__.py
+│   │   ├── core_tools.py        # list_datasets, describe, query, summarize
+│   │   ├── meta_tools.py        # save_analysis, create_tool, manage, etc.
+│   │   └── dynamic_loader.py    # Load user tools from disk, register with MCP
+│   ├── sandbox.py               # Code validation and safe execution
+│   ├── api/
+│   │   ├── __init__.py
+│   │   └── routes.py            # REST API for frontend
+│   └── static/
+│       └── index.html           # Single-file frontend dashboard
+├── tests/
+│   ├── test_ingest.py
+│   ├── test_tools.py
+│   └── test_sandbox.py
+└── sample_data/
+    └── demo.xlsx                # Sample file for testing
+```
+
+## REST API Endpoints (for frontend)
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/` | Serve dashboard HTML |
+| GET | `/api/datasets` | List all tables |
+| GET | `/api/datasets/{table}` | Table details + preview |
+| DELETE | `/api/datasets/{table}` | Drop a table |
+| POST | `/api/upload` | Upload Excel/CSV file |
+| GET | `/api/tools` | List all tools (core + user) |
+| GET | `/api/tools/{id}` | Tool details |
+| POST | `/api/tools` | Create new tool |
+| PUT | `/api/tools/{id}` | Update tool |
+| DELETE | `/api/tools/{id}` | Delete tool |
+| POST | `/api/tools/{id}/test` | Run tool with params |
+| GET | `/api/health` | Health check |
+
+## Dependencies
+
+- `mcp` — MCP SDK
+- `fastapi` — REST API + frontend serving
+- `uvicorn` — ASGI server
+- `pandas` — Data manipulation
+- `openpyxl` — Excel reading
+- `tabulate` — Markdown table formatting
+
+## User Config
+
+`~/.excel-mcp/config.json`:
+```json
+{
+  "data_dir": "~/Documents",
+  "port": 8765,
+  "auto_scan": false,
+  "max_rows_preview": 50,
+  "query_timeout_seconds": 10
+}
+```
+
+## Success Criteria
+
+1. Dave can install with one terminal command (with Blake's help)
+2. Dave can drag Excel files into the dashboard
+3. Dave can ask Claude questions about his data immediately
+4. Dave can tell Claude to save analyses as reusable tools
+5. Dave can see and manage his tools in the dashboard
+6. Dave never needs to write code, SQL, or edit config files
+7. Everything runs locally — Dave's data never leaves his machine

excel_analytics_mcp-0.1.0/excel_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Excel MCP Server — self-evolving data analytics toolkit for Claude Desktop."""
+
+__version__ = "0.1.0"

excel_analytics_mcp-0.1.0/excel_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for ``python -m excel_mcp``."""
+
+from .server import main
+
+main()