hank-excel-mcp

Python package for connecting Excel to AI via MCP.

See the main README for full documentation.

Install

Install this source revision from this directory:

pip install .

The distribution is hank-excel-mcp; the Python import remains excel_mcp and the console command remains excel-mcp. For package development, use pip install -e . instead. The read client is part of source version 0.2.0; this does not assert that version has been published to a package index.

Components

• excel_mcp.mcp_server — MCP stdio server (python -m excel_mcp)
• excel_mcp.relay — relay state and create_relay_app() factory; an embedding application must supply request authentication
• excel_mcp.tool_registry — built-in workbook tools plus register_tools() extensibility
• excel_mcp.mcp_server.channel_status — relay/taskpane health and recovery inspection
• excel_mcp.client — ExcelClient and its injectable ExcelTransport protocol
• excel_mcp.views — typed dictionary views of the existing read responses

The live MCP server exposes channel_status plus the registry-backed workbook tools. Inspect the registered surface in process when changing either owner.

excel-mcp start is a host-repository convenience command that launches api.main:app; it is not a standalone authenticated relay. Portable consumers should embed create_relay_app() with their own request authenticator.

Composable reads

from excel_mcp import ExcelClient, ExcelTransport imports the client without starting or importing the MCP server or relay. The embedding host supplies a transport implementing call, search, and describe; the client contains no credentials, session discovery, or independent operation grants.

ExcelClient exposes read_cells, get_used_range, list_sheets, read_range_csv, read_sheet_csv, and find_cells. Every read requires the current workbook session token through workbook; sheet-scoped reads also require sheet_name. The client forwards that token as the existing _workbook argument. Worksheet enumeration indexes and active-sheet observations are not durable targeting identities.

Responses remain the producer's dictionaries, including additional provenance and CSV coverage/continuation metadata. get_used_range preserves None for an empty sheet; read_cells(include_formulas=True) leaves formula strings in the producer's values array. The views do not normalize or discard fields.

Workbook discovery, current selection, UI control, and workbook mutations remain explicit tools, not client methods. Executor registration determines which read operations are callable; installing this distribution does not grant access to a workbook or expose an operation.

The relay factory export is lazy; create_relay_app remains the factory owned by relay_app.