Excel MCP Server

Warnings

• breaking Tool 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.
  Fix: Update client code and AI agent prompts to use the new, simplified tool names as documented in the server's TOOLS.md.
• breaking The command-line interface (CLI) underwent a significant redesign. Commands and their parameters, including the `--session` parameter, have changed.
  Fix: Refer to the updated CLI documentation or `--help` output for the current command structure and parameters. Update any scripts or integrations using the CLI.
• deprecated The Server-Sent Events (SSE) transport method is deprecated. Streamable HTTP transport is now the recommended method for remote connections.
  Fix: Migrate 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').
• gotcha When 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`.
  Fix: Ensure `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.
• gotcha Attempting 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.
  Fix: Implement 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.

Install

• pip install excel-mcp-server Install from PyPI

Imports

• 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.

Quickstart

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)")