How saisharan0103/excel-mcp-server_v2 works
Project Type & Purpose
• This is an open-source, Python-based MCP (Model Context Protocol) server.
• It exposes Excel-manipulation tools over two transports:
– stdio (stdin/stdout) for local, tool-embedded usage
– SSE (HTTP Server-Sent Events) for remote/HTTP usage
• Clients (AI agents or other MCP-aware tools) issue commands (create/read/modify Excel files) and receive structured responses.
File Structure
• Top-level: build scripts, CI/CD (.github/workflows), packaging (pyproject.toml), documentation (README.md, TOOLS.md), assets (logo).
• src/excel_mcp/: core Python package subdivided into:
– __main__.py: CLI entrypoint (“excel-mcp-server”)
– server.py: transport & MCP request dispatcher
– data.py, workbook.py, sheet.py, cell_utils.py: core data structures & helpers
– formatting.py, chart.py, pivot.py, calculations.py: domain logic modules
– validation.py, exceptions.py: input validation & error handling
README Insights
• Describes two transport modes (stdio vs. SSE)
• Environment variables: EXCEL_FILES_PATH (where files live), FASTMCP_PORT (SSE port)
• Usage patterns: invoked via “uvx excel-mcp-server <transport>” or via HTTP URL
Main Components & Their Interactions
a. Client(s): AI agent or MCP-aware tool
b. Transport Layer:
– StdioTransport: reads commands from stdin, writes responses to stdout
– SSETransport: HTTP endpoints (FastMCP over SSE)
c. MCP Server (server.py):
– Parses MCP requests → routes to tool handlers
d. Tool Handlers / Domain Modules:
– Workbook Management (workbook.py)
– Worksheet & Range Utilities (sheet.py, cell_utils.py)
– Data I/O (data.py)
– Formatting & Styles (formatting.py)
– Charts & Visualizations (chart.py)
– Pivot Tables (pivot.py)
– Calculations (calculations.py)
– Validation & Exceptions (validation.py, exceptions.py)
e. File System / Storage: reads/writes .xlsx files in EXCEL_FILES_PATH or client-supplied paths
f. Configuration & Runtime:
– Environment variables
– Python runtime & dependencies (pyproject.toml)
g. CI/CD & Packaging: GitHub Actions → publish to PyPI
Architectural Patterns & Design Principles
• Modular separation by domain (each Excel feature in its own module)
• Clear transport-handler-domain layering (akin to MVC: Transport → Controller (server.py) → Model (domain modules))
• Environment-driven configuration for portability (12-factor style)
• Single microservice exposing two interchangeable transport modes
How to Represent This
– Use a layered layout, top→down or left→right:
1. Clients (left)
2. Transports (next)
3. MCP Server / Dispatcher
4. Domain Modules
5. File System / Storage (right or bottom)
6. Config & Env (annotated)
• From Client → Transport
• From Transport → Server Dispatcher
• from Dispatcher → Domain Modules (each call flows to the appropriate module)
• From Domain Modules → File System (read/write)
– Indicate the packaging/CI path (GitHub → PyPI) in a corner or as an external pipeline for completeness