Third-party toolUpdated 2026.11.18

Excel MCP on Windows: Connect Claude Code and Codex, Then Verify Formulas

Set up Excel MCP on Windows without Microsoft Excel. Connect Claude Code and Codex, verify saved formulas and calculated values, and fix path and version mismatches.

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 npm claude.ps1 wrapper forwards its arguments. Claude then sees an option intended for the server. Use claude.cmd as above; the same server and arguments registered successfully and reported Connected.
  • Executable not found: clients may inherit a different PATH from PowerShell. The full .exe path avoids dependence on finding uvx at startup. Recreate the registration if you move the virtual environment.
  • A path is outside the allowed directories: sales.xlsx already starts inside the allowed workbook folder. Adding .. moves out of it; repeating workbooks/ 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) and read_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.

Subscribe to AI tool picks and practical advice

Get worthwhile tool picks, test findings and important updates in your inbox.

Get a monthly-updated list of AI tools and Skills right away. We email when there are worthwhile tool picks, test findings or important updates. Unsubscribe anytime. Privacy

Almost done: check your inboxClick the button in the confirmation email and you will get the download link for the tool list. If you do not see it, check your spam or Promotions folder.

Past issues

Or follow us on: