<div align="center">

📊 Excel MCP Server

Fast and efficient spreadsheet analysis through atomic operations, built specifically for AI agents

🇬🇧 English • 🇷🇺 Русский • 🇨🇳 中文 • 🇪🇸 Español • 🇯🇵 日本語 • 🇧🇷 Português

Made with ❤️ for mom by @Jwadow

Analyze Excel spreadsheets with your AI agent through atomic operations — no data dumping into AI context

Works with OpenCode, Claude Code, Codex app, Cursor, Cline, Roo Code, Kilo Code and other MCP-compatible AI agents

Why This Exists • My Mom's Review • What Your Agent Can Do • Installation • 💖 Donate

</div>

---

🔒 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

<details> <summary><b>🎯 Option A: Poetry (Recommended)</b></summary>

Poetry is a modern Python dependency manager (replaces pip+venv+requirements.txt). Install it: pip install poetry or pipx install poetry

Install dependencies:

poetry install

Configure your AI agent:

Add this to your MCP settings (JSON config):

{
  "mcpServers": {
    "excel": {
      "command": "poetry",
      "args": ["run", "python", "-m", "mcp_excel.main"],
      "cwd": "C:/path/to/mcp-excel"
    }
  }
}

Important: Replace C:/path/to/mcp-excel with actual path to the cloned repository.

</details> <details> <summary><b>📦 Option B: pip with virtual environment</b></summary>

Install dependencies:

# Windows
python -m venv venv
venv\Scripts\activate
pip install -e .

# Linux/Mac
python -m venv venv
source venv/bin/activate
pip install -e .

Find Python path in venv:

# Windows
where python

# Linux/Mac
which python

Configure your AI agent:

Add this to your MCP settings (JSON config):

{
  "mcpServers": {
    "excel": {
      "command": "C:/path/to/mcp-excel/venv/Scripts/python.exe",
      "args": ["-m", "mcp_excel.main"],
      "cwd": "C:/path/to/mcp-excel"
    }
  }
}

Important:

• Replace C:/path/to/mcp-excel/venv/Scripts/python.exe with actual path from where python command
• On Linux/Mac use path from which python (e.g., /path/to/mcp-excel/venv/bin/python)

</details> <details> <summary><b>🐍 Option C: System Python (Not Recommended)</b></summary>

Install dependencies globally:

pip install "mcp>=1.1.0" "pandas>=2.2.0" "pydantic>=2.10.0" "xlrd>=2.0.1" "openpyxl>=3.1.0" "psutil>=6.1.0" "python-dateutil>=2.9.0"

Configure your AI agent:

{
  "mcpServers": {
    "excel": {
      "command": "python",
      "args": ["-m", "mcp_excel.main"],
      "cwd": "C:/path/to/mcp-excel"
    }
  }
}

⚠️ Warning: This pollutes your global Python environment. Use Poetry or venv instead.

</details>

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

<details> <summary><b>📋 Complete Tool Reference (25 tools) - Click to expand</b></summary>

📊 File Inspection (5 tools)

inspect_file

Get file structure overview - sheets, dimensions, format. Use for: Initial file exploration, sheet discovery, format validation Returns: Sheet list, row/column counts, file metadata

get_sheet_info

Detailed sheet analysis with auto-header detection. Use for: Understanding data structure, column types, sample preview Returns: Column names/types, row count, sample data (3 rows), header detection info

get_column_names

Quick column enumeration without loading full data. Use for: Schema validation, filter building, column availability checks Returns: Column name list, column count

get_data_profile

Comprehensive column profiling - types, stats, nulls, top values. Use for: Initial data exploration, quality assessment, distribution analysis Returns: Per-column: type, null %, unique count, stats (numeric), top N values Efficiency: Replaces 10+ separate calls (get_column_stats + get_value_counts + find_nulls)

find_column

Locate column across multiple sheets. Use for: Multi-sheet navigation, data discovery, cross-sheet analysis Returns: Sheet list with column locations, indices, row counts (case-insensitive)

---

📥 Data Retrieval (3 tools)

get_unique_values

Extract unique values from a column. Use for: Data exploration, filter building, distinct value discovery, data quality checks Returns: Unique value list, count, truncated flag (if limit exceeded) Default limit: 100 values

get_value_counts

Frequency analysis - top N most common values. Use for: Distribution analysis, identifying dominant categories, data imbalance detection Returns: Value → count dictionary, total count, TSV output Default: Top 10 values

filter_and_get_rows

Retrieve filtered rows with pagination. Use for: Data extraction, sample inspection, detailed analysis, export Returns: Filtered rows (list of dicts), total count, TSV output Pagination: limit/offset support

---

🔍 Filtering & Counting (3 tools)

filter_and_count

Count rows matching conditions with 14 operators. Operators: ==, !=, >, <, >=, <=, in, not_in, contains, startswith, endswith, regex, is_null, is_not_null Logic: Nested AND/OR groups, NOT operator, unlimited conditions Use for: Classification, segmentation, data validation, category counting Returns: Count + Excel formula (COUNTIFS), optional sample rows