Skip to content

Architecture

ExcelMcp uses Windows COM automation to control the actual Microsoft Excel application—not just .xlsx files. Because it drives Excel's official Excel.Application API, it can refresh Power Query, recalculate formulas, refresh PivotTables and the Data Model, evaluate DAX, and run VBA or Python =PY() while preserving existing workbook features.

Two equal entry points

The project ships both an MCP Server and a CLI. They are first-class entry points backed by the same Core commands, parameters, defaults, and validation:

  • MCP Server hosts ExcelMcpService in-process and uses direct method calls, which suits conversational and interactive AI clients.
  • CLI (excelcli) communicates with an ExcelMcpService background daemon over a user-isolated Windows named pipe. The daemon keeps workbook sessions open across CLI invocations for scripting and coding-agent workflows.
MCP Server ──► In-process ExcelMcpService ──► Core Commands ──► Excel COM
CLI ─────────► CLI daemon (named pipe) ─────► Core Commands ──► Excel COM

The entry points run as separate processes, each managing its own Excel instance. They do not share live sessions.

The Service owns command routing and workbook sessions. A separate Service daemon host owns named-pipe acceptance, connection limits, idle shutdown, and connection draining for the CLI process. The MCP Server does not use this pipe: its bridge owns an in-process Service generation and prevents cancellation from an older generation from resetting a newer one.

The CLI also avoids loading the MCP tool schemas into a coding agent's context. In a same-task, same-model benchmark, the CLI workflow used about 59K tokens versus 163K for MCP—a 64% reduction. Actual usage varies by client, model, and workflow.

Core layers

The current decision records explain the reasons and tradeoffs behind these boundaries.

  1. ComInterop (src/ExcelMcp.ComInterop) provides reusable STA threading, session management, COM cleanup, write guards, and OLE message filtering.
  2. Core (src/ExcelMcp.Core) implements Excel operations for Power Query, DAX, VBA, worksheets, ranges, charts, and other domains.
  3. Service (src/ExcelMcp.Service) manages sessions and routes commands; its daemon host provides the CLI's named-pipe process lifetime.
  4. CLI (src/ExcelMcp.CLI) exposes generated command categories and uses a persistent daemon.
  5. MCP Server (src/ExcelMcp.McpServer) exposes generated MCP tools and invokes the service in-process.
  6. Source generators (src/ExcelMcp.Generators*) generate CLI commands, MCP schemas, and skill manifests from Core interfaces.

Real Excel automation

ExcelMcp intentionally uses the Excel COM API rather than rewriting workbook packages. This provides:

  • Excel's own calculation and refresh engines
  • Preservation of formulas, formatting, charts, PivotTables, macros, and the Data Model
  • Interactive authentication for protected workbooks
  • The ability to show Excel and inspect changes as they happen

CLI desktop integration

The CLI daemon keeps sessions alive between commands and exposes a system-tray icon for monitoring sessions, update notifications, save prompts, and stopping the daemon. Excel can remain hidden for speed or be shown and arranged beside an AI assistant for interactive work.

Session lifecycle

Both entry points use explicit sessions:

  1. Open or create a workbook and receive a session ID.
  2. Run one or more operations against that session.
  3. Close the session, optionally saving changes.

This avoids repeatedly opening workbooks and gives ExcelMcp one controlled place to manage COM resources and Excel process shutdown.

Read the development guide for implementation details, or choose an installation path.