Excel MCP Server lets an AI assistant work with local workbooks without opening Microsoft Excel. The Python server maintained by Haris Musa is useful when the deliverable is an actual .xlsx file: a report with data, formulas and a result someone else can open. For a quick explanation of a pasted table, an MCP server adds little. Check the upstream carefully because several unrelated projects use the Excel MCP name.
Install a fixed version
Use PowerShell in a new working directory with uv available. This example pins 2.3.1; older tutorials may use different tool names.
uv venv --python 3.12 .venv
uv pip install --python .\.venv\Scripts\python.exe excel-mcp-server==2.3.1
New-Item -ItemType Directory -Force workbooks | Out-Null
$server = (Resolve-Path .\.venv\Scripts\excel-mcp-server.exe).Path
$books = (Resolve-Path .\workbooks).Path
For Claude Code, register it in this project:
claude.cmd mcp add excel --scope project --env PYTHONUTF8=1 --env PYTHONIOENCODING=utf-8 -- $server stdio --allow-dir $books
claude.cmd mcp list
Look for Connected, then start a fresh Claude Code session in the project. For Codex:
codex mcp add excel --env PYTHONUTF8=1 --env PYTHONIOENCODING=utf-8 -- $server stdio --allow-dir $books
codex mcp list
Codex stores this registration in its user configuration. The server's --allow-dir argument determines which workbooks it can access. Here, a relative path such as sales.xlsx resolves inside workbooks.
Cursor uses an mcpServers entry in .cursor/mcp.json; follow the upstream Cursor example with this executable and the same arguments. In JSON, use forward slashes in Windows paths or escape each backslash.
Three tasks to try
Build a workbook and read it back
Use only Excel MCP. Create sales.xlsx with a sheet named Sales.
Write Region,Amount in A1:B1 and these rows below it:
Taipei,120; Taipei,80; Kaohsiung,50.
Write =SUM(B2:B4) in B5. Read A1:B5 back before reporting success.
The relevant 2.3.1 tools are create_workbook, write_range and read_range. The expected total is 250. Reading the saved range makes the outcome inspectable instead of relying on the assistant's completion message.
Inspect the calculation separately from the formula
Read Sales!A1:B5 in sales.xlsx using read_range with mode=values,
then mode=formulas. Show the two B5 responses separately.
Our responses were 250 and =SUM(B2:B4). This version can calculate supported formulas locally when a saved result is unavailable, so opening the workbook in Excel was unnecessary for this SUM. If another formula cannot be calculated, inspect uncalculated rather than treating an empty result as zero.
Check the folder boundary
Use this read-only request in your disposable working directory:
Try reading ../outside.xlsx through Excel MCP. Record the exact error.
Do not create the file, change settings or move it to bypass the boundary.
We received Path '../outside.xlsx' is outside the allowed directories.. Put ordinary input workbooks inside the allowed folder and address them relative to that folder.
Troubleshooting
error: unknown option '--allow-dir': PowerShell can consume an unquoted--before the npmclaude.ps1wrapper forwards its arguments. Claude then sees an option intended for the server. Useclaude.cmdas above; the same server and arguments registered successfully and reported Connected.- Executable not found: clients may inherit a different PATH from PowerShell. The full
.exepath avoids dependence on findinguvxat startup. Recreate the registration if you move the virtual environment. - A path is outside the allowed directories:
sales.xlsxalready starts inside the allowed workbook folder. Adding..moves out of it; repeatingworkbooks/adds an unwanted extra directory. - A tutorial's tool or parameter does not exist: 2.x changed the interface. This example uses
write_range(at, rows)andread_range(mode). Have the assistant inspect the current schemas before reusing old prompts. - Formula text exists but the value is missing: first confirm the saved formula with
mode=formulas, then inspect the values response for calculation limitations. A stored formula alone does not validate its result.
Cost and boundaries
The local server is MIT licensed and requires neither Excel nor a Microsoft 365 account or service API key. Your AI client's usage is separate. It works with modern workbook formats rather than legacy .xls, and it does not control Excel's visible interface. Validate advanced formulas, macros and PivotTables separately before using them in important workbooks.
If the job is repeated SQL aggregation over CSV data, DuckDB MCP avoids managing cell coordinates. For ordinary text-file access, see Filesystem MCP.
FAQ
Does Excel MCP require Microsoft Excel?
The Haris Musa server used here edits files directly and does not require Excel. Other projects with similar names may depend on COM automation or a running Excel instance. Match the package and repository before following their installation advice.
Can Claude Code and Codex use the same workbook?
They can point to the same allowed folder, but take turns editing a given file. Concurrent saves can overwrite another client's changes. Check the range after each edit; client registration alone says nothing about workbook correctness.
Why does SUM work before the file has been opened in Excel?
Version 2.3.1 has a local calculator for supported formulas without saved results. We read 250 in values mode and the original SUM expression in formulas mode, then independently checked that the expression remained in the file. That demonstrates this calculation, rather than full Excel-engine compatibility.
What we tested
On 2026-11-16, Windows with Python 3.12, excel-mcp-server 2.3.1 and Codex CLI 0.169.0: real workbook creation, values/formulas readback, persisted formula and an outside-folder rejection. Claude Code registration reported Connected. Cursor, large workbooks and advanced formulas were not tested. Setup and feature references: official README and tool reference, accessed the same day.