Install & Compatibility
Where this runs
tested against v0.1.8 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
131MB installed
● package 131MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Server startup
✓ python -m excel_mcp_server
The library runs as a server module; direct Python class imports for client-side interaction are not typical. Clients connect to the running server via MCP.
The Excel MCP Server runs as a standalone process. This quickstart demonstrates setting up essential environment variables. An AI agent or MCP client then connects to this running server. The 'uvx' command is often used as a wrapper for launching the server, especially for different transports. For local interaction, 'stdio' transport is an option, where file paths can be provided per tool call.
import os
# These are example environment variables. For actual usage, they should be set in your shell
# or deployment environment before starting the server.
# For local stdio transport, EXCEL_FILES_PATH is often not required as paths are sent per tool call.
# For SSE/Streamable HTTP, EXCEL_FILES_PATH is crucial.
# OPENAI_API_KEY is an example if the server were to call an LLM provider.
os.environ['EXCEL_FILES_PATH'] = os.environ.get('EXCEL_FILES_PATH', './excel_files')
os.environ['FASTMCP_PORT'] = os.environ.get('FASTMCP_PORT', '8017')
# To start the server using the recommended Streamable HTTP transport:
# You would typically run this in a terminal or as part of a service.
# The server will listen on the specified port.
# Clients (e.g., AI agents) then connect to this endpoint.
# For demonstration, this code block only sets up environment variables. The server itself is a long-running process.
print(f"Excel MCP Server configured to use files in: {os.environ['EXCEL_FILES_PATH']}")
print(f"Excel MCP Server configured to listen on port: {os.environ['FASTMCP_PORT']} (if using HTTP transports)")
print("To start the server, run: uvx excel-mcp-server streamable-http (or python -m excel_mcp_server for older versions)")
excel-mcp-server --version
Debug
Known issues
breakingTool names have been simplified, removing the 'excel_' prefix from many MCP tool names (e.g., 'excel_range' became 'range'). This requires updates in client configurations or prompts.fixUpdate client code and AI agent prompts to use the new, simplified tool names as documented in the server's TOOLS.md.
affects: Prior to 0.1.x, specifically versions around the CLI redesign.
breakingThe command-line interface (CLI) underwent a significant redesign. Commands and their parameters, including the `--session` parameter, have changed.fixRefer to the updated CLI documentation or `--help` output for the current command structure and parameters. Update any scripts or integrations using the CLI.
affects: Prior to 0.1.x, specifically versions around the CLI redesign.
deprecatedThe Server-Sent Events (SSE) transport method is deprecated. Streamable HTTP transport is now the recommended method for remote connections.fixMigrate client connections from SSE to Streamable HTTP transport for improved stability and performance. Update your MCP client configuration accordingly (e.g., from 'url': 'http://localhost:8000/sse' to 'url': 'http://localhost:8000/mcp').
affects: 0.1.x onwards (SSE deprecated).
gotchaWhen using SSE or Streamable HTTP transports, the `EXCEL_FILES_PATH` environment variable must be set on the server side to specify the directory for Excel file storage and access. If not set, it defaults to `./excel_files`.fixEnsure `EXCEL_FILES_PATH` is explicitly set in the server's environment (e.g., `export EXCEL_FILES_PATH=/path/to/excel_files`) to control file locations and prevent security issues related to unexpected file access.
affects: All versions supporting SSE/Streamable HTTP.
gotchaAttempting to perform screen capture operations on Excel files (e.g., `excel_screen_capture`) on Windows can lead to the Excel file remaining locked after the operation, preventing further access or modification.fixImplement robust error handling and file release mechanisms after screen capture. Consider alternative data extraction methods if file locking becomes a persistent issue in automated workflows.
affects: All versions with screen capture functionality on Windows.
Upgrade
Version history
0.1.8latest on PyPI · released Apr 12, 2026
Audit
Dependencies
PythonrequiredRequires Python 3.10 or newer for execution.
MCP SDKrequiredRelies on the Model Context Protocol SDK for communication.
OpenPyXLrequiredUtilizes OpenPyXL for underlying Excel file manipulation.