Architecture

Overview

┌─────────────────┐    stdio     ┌────────────────────┐     COM      ┌─────────┐
│   MCP Client    │ ───────────→ │ mcp-server-xlwings │ ───────────→ │  Excel   │
│ (Claude, Cursor │ ←─────────── │    (Python/MCP)    │ ←─────────── │ Process  │
│  Windsurf, etc.)│   JSON-RPC   └────────────────────┘  Win32 API   └─────────┘
└─────────────────┘

Layers

MCP Client

Claude Desktop, Claude Code, Cursor, Windsurf, Roo Code, Continue — any client that supports the Model Context Protocol. Sends tool calls via JSON-RPC over stdio.

MCP Server

A Python process running FastMCP. Receives tool calls, translates them into xlwings operations, and returns structured JSON responses. Fully stateless — no session management needed.

COM Automation (xlwings)

Connects to the running Excel process via Windows COM (the same interface VBA macros use, Windows only). Can access any file Excel has open, including DRM-protected and encrypted documents.

Excel Process

The actual Microsoft Excel application. Manages files, formulas, macros, and formatting. The user can continue working in Excel while the MCP server operates — they share the same live instance.

Design Principles

Stateless

No session IDs or connection management. Each tool call independently finds the active Excel instance. If Excel is restarted between calls, the next call simply reconnects.

Active Workbook Default

All tools default to the active workbook when workbook is omitted. This eliminates the need to specify file paths for the most common case — working with the file the user currently has open.

Summary-First

read_data() without a cell_range returns sheet structure (dimensions, headers, merged cells, regions) instead of dumping all data. This lets the agent understand the sheet layout before fetching specific ranges, saving context window space.

Minimal Tool Count

11 tools cover the full range of Excel operations. Related actions are consolidated (e.g., manage_workbooks handles list/open/save/close/recalculate) to reduce LLM context overhead.