MaximeSwagel/Excel-MCP

Excel MCP Server

A FastMCP-compatible server that lets assistants inspect, edit, and provision Excel workbooks. The service exposes structured MCP tools backed by openpyxl, offers an optional FastAPI UI for file management, and is packaged to deploy on Fly.io with persistent storage.

Project Structure

• MCPserver.py defines the FastMCP server, tool registry, middleware, and startup/shutdown hooks that configure logging and the Excel workspace path.
• FASTAPIserver.py wraps the MCP server in FastAPI, serves the optional webapp/ assets, and adds REST helpers for uploading, listing, downloading, and deleting spreadsheets.
• run_server.py collects environment variables and boots the combined FastAPI/MCP stack with uvicorn.
• src/
  • data.py, sheet.py, workbook.py implement the read/write operations that power the MCP tools.
  • cell_utils.py parses A1-style ranges so tools can resolve coordinates reliably.
  • exceptions.py and Outputclasses.py centralise error types and structured responses returned to clients.
• webapp/ contains the Vite-built static UI. When webapp/assets exists, it is served alongside the MCP API.
• data/ is the default writable directory for Excel files when running on Fly.io.
• fly.toml configures the Fly.io app, HTTP service, and persistent volume mount.

Runtime Dependencies with uv

This project uses uv to manage Python environments declared in pyproject.toml:

• anyio supplies structured concurrency primitives used by FastAPI and FastMCP.
• fastapi hosts the HTTP endpoints and bridges the MCP server to the web.
• fastmcp provides the Model Context Protocol server runtime, tool decorator, and middleware hooks.
• mcp[cli] bundles the CLI tools that make it easy to test MCP calls locally.
• openpyxl reads and writes Excel workbooks referenced by the MCP tools.
• vite builds the optional web UI that ships at / when assets are present.

Install uv (one time) and sync dependencies:

curl -LsSf https://astral.sh/uv/install.sh | sh  # follow official instructions for your platform
uv sync

uv sync resolves the lockfile, creates a virtual environment, and installs the packages above in one step.

Local Development

1. Ensure uv is installed and run uv sync.
2. Choose a directory for Excel files and export it:

   export EXCEL_FILES_PATH=./excel_files
   mkdir -p "$EXCEL_FILES_PATH"
   

3. (Optional) select a log destination:

   export LOG_FILE_PATH=./logs
   mkdir -p "$LOG_FILE_PATH"
   

4. Launch the server:

   uv run python run_server.py
   

5. The FastAPI app listens on 0.0.0.0:8000. Open / to load the UI (if built) or connect an MCP client to /mcp.
6. Sanity-check the transport:

   uv run mcp ping http://127.0.0.1:8000/mcp
   

Deploying to Fly.io

1. Install the Fly.io CLI and authenticate: fly auth login.
2. Create the app (once): fly launch --no-deploy to keep the generated fly.toml.
3. Provision the persistent volume referenced in fly.toml:

   fly volumes create myapp_data --size 1
   

4. Deploy:

   fly deploy
   

5. Verify the machine and logs: fly status and fly logs.

The Fly configuration exposes port 8000, mounts /app/data, and keeps one machine online so MCP clients can connect immediately. Adjust CPU, memory, or scaling in fly.toml to suit your workload.

Production Notes

• Restrict access to trusted clients or place the service behind an authenticated proxy; the toolset can mutate spreadsheets.
• Validate filenames supplied to upload/delete endpoints to avoid path traversal.
• Monitor excel-mcp.log and excel-mcp-error.log, rotating or exporting logs if required.