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.

Category	Module	Highlights
Workbook	workbook_tools.py	open/create/save/save-as/close/rename/copy/delete, properties, structural password protection, statistics
Worksheet	worksheet_tools.py	create/delete/rename/duplicate/hide/unhide/move/protect/set-active
Cells & ranges	cell_tools.py	read/write single cell & range, copy/move/clear/delete/insert, merge/unmerge, fill series, auto-fill (with formula reference shifting), hyperlinks, named ranges
Formulas	formula_tools.py	insert, find all, find broken (cached errors), replace, formula→value / value→formula, dependency extraction, formula stats, small safe local evaluator
Formatting	formatting_tools.py	font, fill, border, alignment, number formats (incl. accounting/currency/%/scientific), column width/row height, auto-fit, style presets
Tables	table_tools.py	create/delete/rename/resize/restyle native Excel Tables, convert range↔table
Sorting	sort_tools.py	multi-column, case-(in)sensitive, natural sort, custom category order
Filtering	filter_tools.py	AutoFilter, 12 filter conditions (blank/duplicate/contains/range/etc.), optional write-out
Search	search_tools.py	find/replace, regex search/replace, multi-sheet, result highlighting
Duplicates	duplicate_tools.py	find/remove with subset-column support
Data cleaning	cleaning_tools.py	trim, case conversion, null fill/remove/interpolate, split/merge columns, extract email/phone/URL/number, date-format normalization, dtype conversion, z-score/IQR anomaly detection
Analysis	analysis_tools.py	describe, correlation/covariance, frequency tables, group/aggregate, ranking, linear regression, trend forecasting, missing-value & unique-value reports
Statistics	statistics_tools.py	mean/median/mode/variance/std/IQR/skew/kurtosis, confidence intervals, z-scores, t-test, chi-square, ANOVA
Charts	chart_tools.py	native dynamic charts (bar/column/line/pie/doughnut/scatter/bubble/area/radar) and image-rendered charts for types Excel/openpyxl can't script (histogram/waterfall/treemap/sunburst/box/heatmap/combo)
Validation	validation_tools.py	dropdown (literal or range-sourced), number/date rules, custom formula rules, input/error messages
Conditional formatting	conditional_formatting.py	color scales, data bars, icon sets, formula rules, duplicates, top/bottom-N, above/below average, blanks
Freeze/view	freeze_tools.py	freeze/split panes, zoom, gridlines, headings
Images	image_tools.py	insert/resize/move/delete/list/export
Comments	comment_tools.py	add/read/delete/list (classic Notes)
Merge/split	merge_tools.py	merge workbooks, split workbook into files, append sheet across workbooks
Import	import_tools.py	CSV, TSV, JSON, XML, another workbook's sheet
Export	export_tools.py	CSV, JSON, HTML, Markdown, PNG snapshot, PDF (via LibreOffice), multi-sheet batch export
Pivot-style summaries	pivot_tools.py	pandas-computed pivot tables written as live sheets, calculated fields, refresh
Automation / analyst reports	automation_tools.py	batch cell/format/formula operations, KPI summary generator, ABC/Pareto analysis, monthly/quarterly/yearly period reports

"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": "..."}