Excel MCP Server

🇨🇳 中文文档 | 🇺🇸 English

A Model Context Protocol (MCP) server for Microsoft Excel automation. Control Excel directly through AI assistants using natural language — read cells, write formulas, apply formatting, create charts, manage sheets, and 90+ more operations.

Features

Read & Write

• Read cell values, formulas, styles, merged cells
• Set values and formulas with auto type detection
• Copy, paste, find & replace

Formatting & Styles

• Font, color, alignment, borders, number formats
• Conditional formatting (cell value, formula, databar, color scale, icon set, top/bottom, duplicates, etc.)
• Cell styles (gradient fill, pattern fill, tint/shade, diagonal borders, built-in styles)
• Row height, column width, format copying

Data Operations

• Sort (single & multi-column), auto filter
• Remove duplicates, text-to-columns, fill series
• Subtotals, grouping/ungrouping, outline levels
• Data validation (list, number, date, time, text length, custom formula)

Charts

• Create, edit, delete charts (column, bar, line, pie, scatter, area, doughnut, radar)
• Deep editing: trendlines, single-point coloring, data labels, axis config, gridlines
• Export chart as image

Tables (ListObject)

• Create, style, resize Excel tables
• Total row with custom aggregation functions
• Convert tables to/from ranges

Shapes & Textboxes

• Insert, edit, move, delete shapes (rectangle, oval, triangle, star, arrow, etc.)
• Insert and edit textboxes with full formatting

Page Layout & Print

• Page setup (orientation, paper size, margins, zoom, fit-to-pages)
• Print area, print titles, page breaks
• Headers & footers with dynamic fields (date, page number, sheet name)

Sheet Management

• Add, delete, rename, copy, hide, show, activate worksheets
• Tab color, zoom, gridlines, headings visibility
• Split windows, freeze panes, calculation mode

Workbook Properties

• Set document properties (title, author, keywords, etc.)
• Formula auditing (trace precedents, trace dependents)
• Named ranges, comments, hyperlinks, protection

Quick Start

Prerequisites

• Windows with Microsoft Excel installed and running
• Python 3.10+
• An MCP-compatible AI client (Claude Desktop, Cursor, etc.)

Install

git clone https://github.com/yaoyuansh/excel-mcp-server.git
cd excel-mcp-server
pip install -e .

Configure MCP Client

Claude Code:

claude mcp add excel-mcp-server -s user -- uv run --directory C:/path/to/excel-mcp-server excel-mcp-server

Or use the equivalent JSON configuration:

{
  "mcpServers": {
    "excel-mcp-server": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/path/to/excel-mcp-server",
        "excel-mcp-server"
      ]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "excel-mcp-server": {
      "command": "python",
      "args": ["-m", "excel_mcp.server"],
      "cwd": "C:/path/to/excel-mcp-server/src"
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "excel-mcp-server": {
      "command": "python",
      "args": ["-m", "excel_mcp.server"],
      "cwd": "C:/path/to/excel-mcp-server/src"
    }
  }
}

Tools

Tool	Description
list_workbooks	List all open Excel workbooks
list_sheets	List worksheets with used ranges
read_sheet	Read data, styles, charts, tables, shapes, validations, filters, print settings
edit_sheet	Edit with 90+ actions (values, formulas, formatting, charts, tables, shapes, page layout, etc.)
manage_sheets	Add, delete, rename, copy, hide, show, activate worksheets

See docs/TOOLS.md for full API reference.

Architecture

┌─────────────────┐     stdio/HTTP      ┌──────────────────┐
│  AI Assistant   │ ◄──────────────────► │  MCP Server      │
│  (Claude/Cursor)│                      │  (server.py)     │
└─────────────────┘                      └────────┬─────────┘
                                                  │
                                          ┌───────▼─────────┐
                                          │  Excel Core      │
                                          │  (excel_core.py) │
                                          │  win32com COM    │
                                          └───────┬─────────┘
                                                  │ COM API
                                          ┌───────▼─────────┐
                                          │  Microsoft Excel │
                                          │  (running app)   │
                                          └─────────────────┘

Project Structure

excel-mcp-server/
├── .gitignore              # Git ignore rules
├── README.md              # English documentation
├── README_CN.md           # 中文文档
├── LICENSE                # Apache 2.0
├── pyproject.toml         # Python packaging config
├── docs/
│   └── TOOLS.md           # Full API reference (EN + CN)
├── tests/                 # Regression and metadata tests
└── src/
    └── excel_mcp/
        ├── __init__.py    # Package init
        ├── server.py      # MCP server (5 tools)
        └── excel_core.py  # Excel operations engine (90+ actions)

Development

Run the regression test suite:

pip install -e ".[dev]"
pytest

The tests cover package import, MCP tool schemas, license metadata consistency, and protection against accidental lowercase JSON literals (true / false / null) in Python code.

License

Apache 2.0 — see LICENSE

Copyright 2026 yaoyuansh