spire-xls

Spire.XLS MCP Server lets AI agents manipulate Excel workbooks via the Model Context Protocol (MCP) without needing Microsoft Office installed. Built with Python, it exposes a server that can create, read, edit, and convert Excel files, including operations like creating worksheets, reading and writing cell data, applying formulas, formatting, working with charts and pivot tables, and converting Excel files to PDF, HTML, CSV, images, XML, and more. The server communicates over Server-Sent Events (SSE), so clients can stream responses and updates as tasks complete. The typical workflow is to start the server, connect an AI tool through the SSE endpoint, and use the provided tools to perform Excel-related operations in a conversational context.

To use it, first run the server (default port 8000). The project supports customizing the port via FASTMCP_PORT. You can configure clients (e.g., Cursor or other MCP clients) to point at http://localhost:8000/sse and supply environment-specific paths for your Excel files. The integration guide shows how to configure Cursor with a minimal mcpServers section and how to enable access to the Excel tools through your AI assistant./customers can also host the MCP server remotely following the Remote MCP Server guide if SSE needs to be proxied or tunneled.

Prerequisites

• Python 3.10 or higher
• Git

Installation steps

1. Clone the repository and navigate into it:

git clone https://github.com/eiceblue/spire-xls-mcp-server.git
cd spire-xls-mcp-server

2. Install the server in editable mode using uv (assumes you have uv installed):

uv pip install -e .

3. (Optional) Install dependencies and verify environment is set up correctly. The server uses Python and requires the Spire.XLS library per the repository’s setup; ensure your Python environment has network access to install packages.

# If you use a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate     # Windows
uv pip install -e .

4. Start the server (default port 8000):

uv run spire-xls-mcp-server

5. To use a custom port (e.g., 8080):

export FASTMCP_PORT=8080 && uv run spire-xls-mcp-server

On Windows PowerShell:

$env:FASTMCP_PORT = "8080"; uv run spire-xls-mcp-server

Environment variables:

• FASTMCP_PORT: Server port (default 8000).
• EXCEL_FILES_PATH: Directory for Excel files (default ./excel_files).

Integration notes:

• This MCP server uses Server-Sent Events (SSE) for transport. If you need to connect from environments that require stdio, consider a gateway like Supergateway to convert SSE to stdio.
• The server is Python-based and does not require Microsoft Office.
• For Cursor integration, you typically add an mcpServers entry that points to the SSE endpoint and optionally sets EXCEL_FILES_PATH to a location containing your Excel files.

Common issues:

• Ensure your Python environment has network access to install dependencies.
• If the server fails to start on a custom port, check firewall or port bindings.
• When pointing tools at EXCEL_FILES_PATH, ensure the path exists and has appropriate read/write permissions.