multi-transport mcp server with stdio, http/sse, and streamable protocols
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.
Unique: Uses FastMCP's @mcp.tool() decorator pattern to define tools once and expose them across three independent transport protocols (stdio, HTTP/SSE, streamable HTTP) without code duplication, with environment-based path handling that differs per transport mode (client-provided paths for stdio, EXCEL_FILES_PATH for HTTP/SSE)
vs alternatives: Eliminates transport-specific tool implementations that plague multi-protocol servers; FastMCP's decorator approach is simpler than manual JSON-RPC routing and supports streaming natively, unlike basic REST API wrappers
openpyxl-backed workbook creation and metadata retrieval
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.
Unique: Leverages openpyxl's pure-Python implementation to eliminate Excel dependency entirely, enabling workbook operations in restricted environments (containers, serverless) where COM/VBA automation is unavailable; wraps openpyxl's Workbook and metadata APIs to expose both creation and introspection in a single tool interface
vs alternatives: Faster than pywin32 (which requires Excel installation) and more reliable than xlwings in headless environments; openpyxl's in-memory workbook model avoids file locking issues that plague Excel COM automation
error handling and response formatting with mcp-compliant error codes
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.
Unique: Maps openpyxl and Python exceptions to MCP-compliant error codes (-32600, -32603, etc.) with structured error responses that include context (operation, file, root cause) without exposing sensitive details; error handling is consistent across all tools through centralized exception mapping
vs alternatives: MCP-compliant error codes enable client-side error handling without parsing error messages; structured error responses are more machine-readable than plain text exceptions; centralized error mapping is more maintainable than per-tool error handling
concurrent workbook access with in-memory state management
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.
Unique: Eliminates file locking through stateless, request-scoped workbook loading — each tool invocation loads the workbook fresh from disk, performs operations in memory, and saves atomically, avoiding the persistent file handles that cause Excel COM lock contention; openpyxl's in-memory model enables parallel processing without coordination
vs alternatives: More scalable than xlwings which maintains persistent Excel COM connections; avoids file locking issues that plague shared Excel file access; stateless design enables horizontal scaling (multiple server instances) without shared state coordination
intelligent data read/write with header detection and type inference
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.
Unique: Combines openpyxl's cell-level access with heuristic type inference (date regex, numeric parsing) to automatically convert raw Excel values into typed Python objects without schema specification; header detection scans first row to create dict keys, enabling schema-free data extraction that adapts to varying Excel layouts
vs alternatives: Requires no schema definition unlike pandas.read_excel with dtype specification; faster than pandas for small-to-medium datasets because it avoids DataFrame overhead; more flexible than xlrd/xlwt which don't support modern .xlsx format or type preservation
worksheet lifecycle management (create, copy, delete, rename)
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.
Unique: Uses openpyxl's worksheet collection API to perform atomic sheet operations (create via add_sheet, copy via copy_worksheet, delete via remove, rename via title property) with validation logic to maintain workbook integrity; sheet copying preserves formulas and formatting through openpyxl's internal cell cloning mechanism
vs alternatives: More reliable than manual sheet duplication (copy-paste approach) because it preserves internal formula references; simpler than xlwings which requires Excel COM object model; openpyxl's in-memory model avoids file locking during sheet operations
range-based cell formatting with styles, fonts, colors, borders, and merging
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.
Unique: Wraps openpyxl's Style, Font, PatternFill, Border, and Alignment classes to apply multi-attribute formatting in a single operation, avoiding the need for sequential cell-by-cell style assignments; range parsing converts Excel notation (A1:C10) to cell coordinates for batch application
vs alternatives: Faster than xlwings for bulk formatting because it operates on in-memory objects without Excel COM overhead; more flexible than pandas.ExcelWriter which has limited styling options; openpyxl's object-oriented style API is cleaner than xlrd/xlwt's tuple-based formatting
formula application and syntax validation
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.
Unique: Separates formula syntax validation (regex-based, no execution) from formula application (openpyxl cell assignment), enabling early error detection without side effects; supports both formula-as-reference mode (editable in Excel) and data_only mode (calculated values only) through openpyxl's dual-mode loading
vs alternatives: Validation without execution avoids the cost of opening Excel or running formulas; openpyxl's formula parser is more accurate than regex-only validation; supports modern Excel functions better than xlrd/xlwt which have limited formula support
+4 more capabilities