excel-mcp-server

Implements a Model Context Protocol server using FastMCP framework that bridges three distinct transport mechanisms (stdio for local IDE integration, HTTP with Server-Sent Events for remote services, and streamable HTTP for streaming responses) to the same underlying Excel operation logic. The server uses typer CLI to provide mode selection at startup, abstracting transport complexity from tool implementations while maintaining protocol-agnostic tool definitions via @mcp.tool() decorators.

Provides programmatic workbook creation and metadata extraction using the openpyxl library, which operates without requiring Microsoft Excel installation. The implementation wraps openpyxl's Workbook class to create new Excel files with configurable properties (title, author, subject, keywords) and retrieves workbook-level metadata including sheet names, dimensions, and document properties through openpyxl's metadata API.

Implements comprehensive error handling that catches openpyxl exceptions, file I/O errors, and validation failures, then formats them as MCP-compliant error responses with structured error codes and human-readable messages. The server uses try-except blocks in each tool to catch specific exceptions (FileNotFoundError, ValueError, openpyxl.utils.exceptions.InvalidFileException) and maps them to MCP error codes (e.g., -32600 for invalid request, -32603 for internal error). Error responses include context information (file path, operation, root cause) to aid debugging without exposing sensitive system details.

Manages multiple concurrent Excel workbook operations through openpyxl's in-memory workbook model, where each tool call loads a workbook into memory, performs operations, and saves changes back to disk. The server does not maintain persistent workbook state between requests — each request is stateless and independent. This approach avoids file locking issues that plague Excel COM automation but requires explicit save operations after modifications. The implementation uses openpyxl's load_workbook() and save() methods with optional data_only parameter to control formula evaluation.

Implements bidirectional data operations that automatically detect Excel headers, infer data types, and handle sparse data ranges. The read operation scans the first row to identify headers, then extracts data with type preservation (dates, numbers, strings). The write operation accepts structured data (list of dicts or 2D arrays) and intelligently maps columns to existing headers or creates new ones, with optional header row insertion and cell-level type coercion through openpyxl's cell value assignment.

Provides CRUD operations for Excel worksheets through openpyxl's worksheet API. Creation adds new sheets with optional positioning and default properties. Copy duplicates an entire sheet including formulas, formatting, and data while optionally renaming. Delete removes sheets with validation to prevent removing the last sheet. Rename updates sheet names with collision detection. All operations maintain workbook integrity and update internal sheet references.

Applies visual formatting to cell ranges using openpyxl's Style, Font, PatternFill, Border, and Alignment objects. The format_range operation accepts a range specification (e.g., 'A1:C10') and applies multiple style attributes (font color, background color, bold, italic, borders, alignment) in a single operation. Merge and unmerge operations combine or split cells while preserving content in the top-left cell. All formatting is applied directly to the openpyxl cell objects without requiring Excel to be running.

Enables programmatic formula insertion and validation using openpyxl's formula handling. The apply_formula operation accepts a cell reference and formula string (e.g., '=SUM(A1:A10)'), assigns it to the cell, and optionally calculates the result if data_only mode is enabled. The validate_formula_syntax operation parses formula strings to detect syntax errors (unmatched parentheses, invalid function names, circular references) without executing the formula, using regex-based validation and openpyxl's formula parser.

Generates Excel charts programmatically using openpyxl's Chart classes (LineChart, BarChart, PieChart, ScatterChart, etc.). The create_chart operation accepts a chart type, data range, optional categories/series configuration, and chart properties (title, axis labels). Charts are bound to worksheet data ranges through openpyxl's add_data() and set_categories() methods, which establish dynamic links to source cells. Charts are then embedded in the worksheet at a specified anchor cell.

Generates Excel pivot tables programmatically using openpyxl's PivotTable class. The create_pivot_table operation accepts a source data range, field specifications (row fields, column fields, value fields with aggregation functions like SUM, COUNT, AVERAGE), and optional filtering/sorting. Pivot tables are created in a separate worksheet and linked to the source data through openpyxl's pivot table API, which generates the underlying XML structure without requiring Excel to be running.

Creates native Excel tables (ListObjects in Excel terminology) using openpyxl's Table class, which enables built-in filtering, sorting, and structured references. The create_table operation accepts a data range, optional table name, and style template. Tables are created with automatic header row detection and built-in filter buttons on each column header. The implementation uses openpyxl's Table and TableStyleInfo classes to apply predefined Excel table styles (Light1, Medium2, Dark3, etc.) without manual cell-by-cell formatting.

Implements transport-specific file path resolution logic that adapts to the deployment context. For stdio transport (local IDE integration), file paths are provided by the client with each tool call, enabling flexible per-request path specification. For HTTP/SSE transports (remote deployment), the server reads the EXCEL_FILES_PATH environment variable to establish a root directory, and all file operations are scoped to this root with path traversal protection. The implementation uses os.path.join() and path normalization to prevent directory escape attacks while maintaining cross-platform compatibility.