jwadow/mcp-excel

---

🔒 Data Security & Privacy

Local-First Architecture This server runs entirely on your local machine. Your Excel files are processed locally and never leave your computer.

Is it safe?

• Local Models (Ollama, LM Studio): Your data never leaves your machine. 100% private.
• Cloud Models (OpenRouter, ChatGPT): Only the precise results of operations (counts, sums, formulas) and metadata (column names) are sent to the model. The bulk raw data remains on your disk.

---

🤨 Why This Exists

The Problem: Most Excel tools for AI dump raw spreadsheet data into the agent’s context. This floods the context window, slows everything down, and the AI can still miscalculate or get confused in large datasets.

This Project: Think SQL for Excel. Your AI agent composes atomic operations (filter_and_count, aggregate, group_by) and gets back precise results — not thousands of rows.

The agent analyzes data without seeing it. Results come as numbers, formulas, and insights.

“This is like working with a database through SQL, not dragging everything into memory.” — AI Agent after analyzing a production spreadsheet

🔌 What is MCP?

Model Context Protocol is an open standard that lets AI agents use external tools.

This project is such a tool. When you connect this server to your AI agent (OpenCode, Claude Code, Codex app, Cursor, Cline, Roo Code, Kilo Code, etc.), your agent gets a lot of new commands for working with Excel files — filtering, counting, aggregating, analyzing.

The key benefit: Your AI doesn’t load thousands of spreadsheet rows into its memory. Instead, it asks specific questions and gets precise answers. Faster, more accurate, no context overflow.

---

👩 My Mom’s Review

Translated from Russian. She’s not a tech person - types with one finger, uses Excel every day for work.

“Usually takes me an hour to break down this spreadsheet, filter by categories, copy into different columns, calculate totals. Gave it the task and it did everything in 3 minutes. Checked it and its correct. Now its like this with any task, just write what I need and it does it. I’m honestly shocked. Half my life I’ve been doing this by hand and the computer just gets what I need. Saving so much time for real.”

---

🚀 What Your Agent Can Do

Once connected, your AI agent gets a lot of specialized tools for analyzing spreadsheet data. The agent receives only precise queries and reliable results.

📊 Data Exploration

• Inspect files - structure, sheets, columns, data types (auto-detects messy headers)
• Profile columns - statistics, null counts, top values, data quality in one call
• Find data - search across multiple sheets, locate columns anywhere

🔍 Filtering & Querying

• 12 filter operators - ==, !=, >, =, <=, in, not_in, contains, startswith, endswith, regex
• Complex logic - nested AND/OR groups, NOT operator, unlimited conditions
• Batch operations - classify data into multiple categories in one request (6x faster)
• Overlap analysis - Venn diagrams, intersection counts, set operations

📈 Aggregation & Analysis

• 8 aggregation functions - sum, mean, median, min, max, std, var, count
• Group by - pivot tables with multiple grouping columns
• Statistical analysis - correlations (Pearson/Spearman/Kendall), outlier detection (IQR/Z-score)
• Time series - period-over-period growth, moving averages, running totals

🏆 Advanced Operations

• Ranking - top-N, bottom-N, percentile ranking (with grouping support)
• Calculated columns - arithmetic expressions between columns
• Data validation - find duplicates, null values, data quality checks
• Sheet comparison - diff between versions, find changes

⚡ Performance Features

• Atomic operations - results in 20-50ms, no matter the file size
• Smart caching - file loaded once, reused for all operations
• Sample rows - preview filtered data without full retrieval
• Context protection - smart limits prevent AI context overflow

📋 Excel Integration

• Formula generation - every result includes Excel formula for dynamic updates
• TSV output - copy-paste results directly into Excel
• Legacy support - works with old .xls files (Excel 97-2003)
• Multi-sheet - analyze across multiple sheets in one file

Example queries your agent can now handle:

• “Show me top 10 customers by revenue”
• “Find all orders from Q4 where amount > $1000”
• “Calculate month-over-month growth for each product category”
• “Which customers are both VIP and active? (overlap analysis)”
• “Find duplicates in the email column”

⚙️ Installation & Configuration

Prerequisites

Python 3.10 or higher — Download here

Step 1: Clone Repository

git clone https://github.com/jwadow/mcp-excel.git
cd mcp-excel

No Git? Click “Code” → “Download ZIP” at the top of this repository page, extract, and open terminal in that folder.

Step 2: Choose Installation Method

Step 3: Verify Installation

Restart your AI agent and test:

"Analyze the Excel file at C:/Users/YourName/Documents/test.xlsx"

If it works - you’re done! If not, check:

• Path to repository is correct in cwd
• Python path is correct in command (for pip method)
• All dependencies are installed

Supported AI Agents

Works with any MCP-compatible AI agent.

⚠️ Important: This is an MCP server. It runs automatically when your AI agent needs it. Do not run it manually in terminal.

💡 Usage

After configuration, restart your AI agent and ask it to analyze Excel files:

"Analyze the Excel file at C:/Users/YourName/Documents/sales.xls"
"Show me top 10 customers by revenue from sales.xlsx"
"Find duplicates in column 'Email' in contacts.xlsx"
"Calculate month-over-month growth from revenue.xls"

🛠️ Available Tools

🗺️ Roadmap

📁 File Format Support

Currently Supported:

• ✅ XLS - Excel 97-2003 (read-only)
• ✅ XLSX - Excel 2007+ (read-only)

Planned:

• 🔜 XLSM - Excel with macros support
• 🔜 CSV - Comma-separated values
• 🔜 TSV - Tab-separated values
• 🔜 ODS - OpenDocument Spreadsheet
• 🔜 Parquet - Columnar storage format

🚀 Features

• Write operations - Modify spreadsheets files (create calculated columns, update values)
• SSE transport mode - Server-Sent Events for remote access
• Advanced formula generation - More complex Excel formulas with nested functions
• Data export - Export filtered/aggregated results to new files

---

📜 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

This means:

• ✅ You can use, modify, and distribute this software
• ✅ You can use it for commercial purposes
• ⚠️ You must disclose source code when you distribute the software
• ⚠️ Network use is distribution — if you run a modified version on a server and let others interact with it, you must make the source code available
• ⚠️ Modifications must be released under the same license

See the LICENSE file for the full license text.

Why AGPL-3.0?

AGPL-3.0 ensures that improvements to this software benefit the entire community. If you modify this server and deploy it as a service, you must share your improvements with your users.

---

💖 Support the Project

---

🤝 Contributing

Contributions are welcome! Please ensure:

1. All dependencies are AGPL-compatible
2. Code follows the existing style
3. Tests are included for new features
4. Documentation is updated

For issues, questions, or contributions, please open an issue on GitHub.

---

💬 Need Help?

Got questions? Found a bug? Have a feature idea? We’re here to help!

👉 Open an Issue on GitHub

Whether you’re stuck with installation, found something broken, or just want to suggest an improvement — GitHub Issues is the place. Don’t worry if you’re new to GitHub, just click the link above and describe your situation. We’ll figure it out together.

---