Skip to main content
Glama
Feynman520

excel-engine-mcp

by Feynman520
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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 Server

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)

#

Tool

Input → Output

Why engine-only

①

excel_recalculate

src_path, out_path → {out_path}

Full dependency recalculation — libraries write formulas but cannot compute them

②

excel_read_values

path, sheet?, cell_range?, recalc? → {sheet,address,rows,cols,values,text}

Reads computed cell values (openpyxl only has the formula strings)

③

excel_export_pdf

src_path, out_path, sheet?, recalc? → {out_path}

WYSIWYG PDF via Excel's render engine (print areas, fit-to-page, headers/footers)

—

excel_health

→ {alive, excel_version}

Session check (launches Excel on first call)

—

excel_restart

→ {alive}

Recovery from COM errors

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • xlwings Excel MCP Server

    hyunjae-labs
    F
    license
    A
    quality
    F
    maintenance
    Enables Excel file manipulation through Microsoft's official COM automation interface using xlwings, designed for corporate environments where security policies prevent direct file access. Provides 25 tools for workbook operations, data manipulation, formatting, charts, pivot tables, and worksheet management through native Excel integration.
    29
    9
    -

  • Excel MCP Server

    Samcil
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables reading and writing of values, formulas, and formatting in Microsoft Excel files including .xlsx and .xlsm formats. It supports sheet management, table creation, and provides Windows-exclusive features like live editing and screen capture.
    8,110 npm
    MIT

  • Excel MCP Server

    LOCAL2
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables reading and writing MS Excel data, including values, formulas, sheets, tables, and cell formatting, with optional screen capture on Windows.
    8,110 npm
    MIT