excel-engine-mcp

한국어 안내 → README.ko.md

A local MCP server that drives the real Excel desktop application (COM automation) to do the things file-manipulation libraries (openpyxl etc.) fundamentally cannot: recalculate formulas, read computed cell values, and render true-fidelity PDF.

Design philosophy: this server complements library workflows instead of replacing them. Writing static cells and bulk data is faster with openpyxl — but openpyxl only stores formula strings (reading them back gives None), and no library has Excel's render engine. This MCP handles only the engine-exclusive part, keeping its tool surface tiny (5 tools).

Requirements

• Windows 10+ with a logged-in interactive desktop session (Excel has no true headless mode)

• Microsoft Office (Excel) installed and licensed — verified on Office 2016+ (Excel 16.0)

• Python 3.10+ — verified on 3.12

• Claude Code or any MCP client

Related MCP server: excel-mcp-rw

Install

git clone https://github.com/Feynman520/d01-p02-excel-engine-mcp.git
cd d01-p02-excel-engine-mcp
py -3.12 -m venv .venv          # or: python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Register with Claude Code

Run this in the cloned folder (uses absolute paths, so it works from anywhere afterwards):

claude mcp add excel-automation --scope user -- "$PWD\.venv\Scripts\python.exe" "$PWD\server.py"

--scope user makes it available in every project. Use --scope project to limit it to one project.

Verify

$py = ".\.venv\Scripts\python.exe"; $env:PYTHONUTF8 = "1"
& $py tests\smoke_com.py      # COM recalc / computed values / PDF / zombie cleanup
& $py tests\server_tools.py   # MCP tool registration (does not launch Excel)

Tools (3 core + 2 diagnostics)

Typical flow: write inputs with openpyxl → excel_recalculate to bake real values → excel_read_values to verify / excel_export_pdf for the final PDF. Originals are never modified; results are always written to out_path.

Architecture notes

• Single STA worker thread (engine/session.py): win32com COM objects are bound to the thread that created them, while FastMCP may hop threads — so every Excel call is serialized onto one dedicated thread.

• Lazy session: Excel starts on the first tool call, is reused across calls, and is closed when the server stops.

• DispatchEx + early binding (gencache.EnsureDispatch): a dedicated Excel instance (never attaches to the user's open Excel), called through the type library. ⚠️ ExportAsFixedFormat fails with 1004 (0x800A03EC) under late binding due to optional argument marshalling — early binding is required.

• Zombie prevention: after Quit(), any surviving dedicated Excel process is force-killed by PID (identified via the main window handle).

• RPC-rejection retry: RPC_E_CALL_REJECTED right after startup is retried with backoff.

• stdout protection: the one-time makepy cache generation output is redirected to stderr (stdout is the JSON-RPC channel).

Limitations

• Not suitable for unattended/service sessions (needs an interactive desktop).

• Bulk static writes are faster with libraries — that is by design.

License

MIT