Excel MCP Server

A production-structured Model Context Protocol server that gives Claude (or any MCP client) deep, tool-level control over Microsoft Excel files (.xlsx, .xlsm, .csv, .tsv) — reading, writing, formatting, formulas, charts, pivot-style summaries, data cleaning, statistics, and export, all exposed as 164 individual MCP tools across 24 modules.

1. What's actually implemented

This covers the vast majority of the original 300+ item feature spec as real, tested tools. A handful of items have genuine platform limitations — see Section 6 before you rely on them.

"AI features" ("what caused sales to drop?", "find business insights", etc.) are not a separate tool — that's exactly what Claude does natively by chaining describe_dataset → correlation_matrix → forecast_trend → detect_anomalies and reasoning over the JSON results. No extra tool needed; just ask Claude the question once the file is open.

2. Project structure

excel-mcp/
├── server.py                 # FastMCP entrypoint, registers all tool modules
├── config.py                 # logging, path/workspace safety settings
├── requirements.txt
├── README.md
├── tools/
│   ├── workbook_tools.py
│   ├── worksheet_tools.py
│   ├── cell_tools.py
│   ├── formula_tools.py
│   ├── formatting_tools.py
│   ├── table_tools.py
│   ├── sort_tools.py
│   ├── filter_tools.py
│   ├── search_tools.py
│   ├── duplicate_tools.py
│   ├── cleaning_tools.py
│   ├── analysis_tools.py
│   ├── statistics_tools.py
│   ├── chart_tools.py
│   ├── validation_tools.py
│   ├── conditional_formatting.py
│   ├── freeze_tools.py
│   ├── image_tools.py
│   ├── comment_tools.py
│   ├── merge_tools.py
│   ├── import_tools.py
│   ├── export_tools.py
│   ├── pivot_tools.py
│   └── automation_tools.py
└── utils/
    ├── helpers.py             # path safety, workbook registry, response envelopes, pandas bridge
    └── constants.py           # number formats, regex patterns, chart type maps

3. Installation

Requirements: Python 3.10+ (3.12 recommended).

cd excel-mcp
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Optional, for export_to_pdf only: install LibreOffice (sudo apt install libreoffice / brew install --cask libreoffice / Windows installer). Every other tool works without it.

Test the server starts cleanly:

python server.py

It will sit waiting for an MCP client on stdio (this is expected — it's not meant to print anything when run standalone). Press Ctrl+C to stop.

4. Claude Desktop configuration

Add this to your Claude Desktop MCP config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "excel": {
      "command": "/absolute/path/to/excel-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/excel-mcp/server.py"],
      "env": {
        "EXCEL_MCP_ROOT": "/absolute/path/to/a/folder/you/want/Claude/to/access"
      }
    }
  }
}

On Windows, command would be something like C:\\path\\to\\excel-mcp\\.venv\\Scripts\\python.exe.

EXCEL_MCP_ROOT is optional — it's just documentation of intent for you; the server itself validates file extensions and existence but does not hard-sandbox to that folder (see Section 7). Restart Claude Desktop after editing the config.

5. Example prompts

• "Open ~/Documents/Q3_Sales.xlsx and give me a KPI summary of Units and Revenue by Region."

• "Create a new workbook with a sales table, add a column chart, and format the header row blue with white bold text."

• "Find and highlight all duplicate rows in the Customers sheet based on Email."

• "Clean up the PhoneNumbers column — trim whitespace and extract just the digits."

• "Run a correlation matrix on my numeric columns and tell me what's most correlated with Revenue."

• "Forecast next 3 months of sales based on the Monthly Total column."

• "Do an ABC/Pareto analysis of my products by revenue."

• "Add a dropdown validation to column C with options Low/Medium/High."

• "Export the Summary sheet to a Markdown table."

6. Known limitations (read before relying on these)

• Formula calculation: openpyxl (and therefore this server) never runs Excel's calculation engine. Formulas are written as strings; evaluate_formula_locally can only evaluate standalone literal expressions (no cell references), and find_broken_formulas / convert_formulas_to_values only see the cached results Excel itself last saved. To get fresh calculated results, open the file in Excel/LibreOffice and save once.

• Native PivotTables: openpyxl cannot author real PivotTable/PivotCache/Slicer XML objects — only Excel can write that format. pivot_tools.py computes the same result with pandas and writes it as a plain (very pivot-table-looking) sheet instead. It won't have a field-list pane or be "refreshable" by clicking a button in Excel, but refresh_pivot_summary does the same job from Claude.

• VBA macros: not implemented. openpyxl can preserve existing macros in a .xlsm file (keep_vba=True, used automatically) but cannot safely author new VBA — that's an intentional omission, since generated macro code is also a common malware vector.

• Threaded (Excel 365) comments: comment_tools.py writes classic "Notes," not the newer threaded Comments format, which uses a different XML part openpyxl doesn't support writing.

• PDF export: requires LibreOffice installed on the host (export_to_pdf will tell you if it's missing); there's no pure-Python way to reproduce Excel's print/pagination engine.

• Password protection: protect_workbook/protect_sheet add Excel's structural/UI protection (deters casual editing) — they do not encrypt the file the way Excel's "Encrypt with Password" does. Don't rely on this for confidentiality.

• AutoFit: auto_fit_columns is a character-count heuristic; openpyxl has no access to Excel's actual font-metrics engine, so results are close but not pixel-perfect.

• Exotic chart types: histogram/waterfall/treemap/sunburst/box-plot/heatmap/combo charts are rendered as static images (matplotlib), not live Excel chart objects, since openpyxl has no writer for them.

7. Security notes

• Every tool validates file extensions against an allow-list (.xlsx .xlsm .xltx .xltm .csv .tsv .xlsb).

• New-file tools (create_workbook, save_workbook_as, exports, etc.) require overwrite=true before replacing an existing file.

• delete_workbook requires an explicit confirm=true flag.

• File size is capped at 250 MB by default (config.MAX_FILE_SIZE_MB) to avoid pathological loads.

• This server does not sandbox file access to a single directory by default — it can read/write anywhere the OS user running it has permissions, the same way a desktop Excel installation would. If you want a hard boundary, run it under an OS user with restricted filesystem permissions, or add a path-prefix check to utils/helpers.safe_path() (one extra if statement) tying it to config.WORKSPACE_ROOT.

• All tool functions catch exceptions internally and return {"success": false, ...} rather than raising — a single bad call cannot crash the server process.

8. Testing

A quick manual smoke test (also how this server was validated during development):

import asyncio
from server import mcp

async def main():
    tool = await mcp.get_tool("create_workbook")
    result = await tool.run({"file_path": "/tmp/test.xlsx", "overwrite": True})
    print(result.structured_content)

asyncio.run(main())

For a fuller check, list every registered tool:

import asyncio
from server import mcp
print(len(asyncio.run(mcp.list_tools())))   # -> 164

9. Logging & error handling

• Logs go to stderr (never stdout — stdout is reserved for the MCP JSON-RPC stream) and to a rotating file at ~/.excel_mcp/logs/excel_mcp_server.log (override with EXCEL_MCP_LOG_DIR).

• Every tool returns a consistent envelope:

  {"success": true, "message": "...", "data": {...}}
  {"success": false, "error_type": "WriteError", "message": "..."}