SwiftExcelMCP

SwiftExcelMCP is a Swift-native Model Context Protocol (MCP) server for Excel workflows on macOS. It ships as a stdio server executable plus a reusable core library, with a safety-first workbook model, structured JSON-RPC errors, and broad test coverage across workbook lifecycle, editing, routing, resilience, and advanced workbook metadata.

Project Status

• Swift package products:
  • SwiftExcelMCPCore library
  • SwiftExcelMCP executable
• Platform: macOS 13+
• Transport: stdio
• Current runtime mode: degraded-by-design default with file fallback available and live Excel automation scaffolded behind capability diagnostics

Repository Layout

.
├── Package.swift
├── Scripts/
│   ├── lint.sh
│   └── mcp_smoke.py
├── Sources/
│   ├── SwiftExcelMCP/
│   │   └── main.swift
│   └── SwiftExcelMCPCore/
│       ├── SwiftExcelServer.swift
│       ├── WorkbookSessionManager.swift
│       ├── HybridRouting.swift
│       ├── ToolCatalog.swift
│       └── ...
└── Tests/
    └── SwiftExcelMCPTests/

What It Supports

• Workbook lifecycle: create, open, inspect, save, close, finalize
• Session safety: stable workbook identifiers, dirty-state tracking, drift detection, read-only and lock protection
• Workbook editing: typed cells, rectangular ranges, formulas, formatting, sheet lifecycle, and batch updates
• Advanced workbook metadata: tables, named ranges, validations, charts, drawing objects, workbook structure, macro-aware inspection, analysis, and repair previews
• Capability and routing diagnostics so clients can see whether live Excel automation or file-backed handling is available

Safety Model

• The server is designed around MCP-managed workbook sessions instead of hijacking arbitrary user workbooks.
• Dirty edits are tracked explicitly and unsafe close/finalize operations are rejected.
• Macro execution requires an explicit tool call; inspect/analyze/repair flows do not implicitly run macros.
• The default live route is intentionally unavailable in the shipped scaffold, so capability inspection reports degraded mode and the file-backed route remains the safe active path.

Requirements

• macOS 13+
• Swift toolchain with swift
• swift format available for linting
• Python 3 for the smoke test helper
• Microsoft Excel is only required for future live-automation validation paths; the current default scaffold remains file-fallback oriented

Build

swift build

Run

Start the stdio MCP server:

swift run SwiftExcelMCP

The executable reads one JSON-RPC request per line from stdin and emits responses on stdout.

Validation

Run the main local checks from the repository root:

swift test --parallel
Scripts/lint.sh

You can also smoke-test the built MCP binary after swift build has completed:

python3 Scripts/mcp_smoke.py "$(swift build --show-bin-path)/SwiftExcelMCP"

Tool Surface

The server exposes workbook and introspection tools including:

• Lifecycle and inspection: create_workbook, open_workbook, list_workbook_sessions, get_workbook_session, inspect_workbook, close_workbook, finalize_workbook
• Cell and range editing: read_cell, write_cell, read_range, write_range, apply_workbook_batch, set_cell_format
• Sheet operations: add_sheet, rename_sheet, reorder_sheet, delete_sheet
• Advanced operations: create_table, update_table, list_tables, create_chart, update_chart, list_charts, insert_image, insert_shape, list_drawing_objects, create_named_range, update_named_range, delete_named_range, list_named_ranges, set_data_validation, clear_data_validation, list_data_validations
• Macro and routing utilities: run_macro, analyze_workbook_advanced, repair_workbook_advanced, edit_vba_module, inspect_workbook_structure, inspect_capabilities, get_route_diagnostics

Test Coverage

The suite includes focused coverage for:

• MCP protocol initialization and error handling
• Session lifecycle and save/finalize safety
• Typed values, formulas, ranges, sheets, and formatting
• Batch mutation semantics and inspection payloads
• Hybrid routing, dirty-state continuity, and resilience safety
• Advanced tables, named ranges, validations, charts, drawings, macros, analysis, and repair
• Lint script contract verification