Excel MCP Server (excel-mcp, PyPI: luiccian-excel-mcp) is a high-performance Python server implementing the Model Context Protocol (MCP) to provide advanced, token-optimized Excel spreadsheet (.xlsx) creation, batch synthesis, formula automation, and inspection capabilities for AI assistants (Claude, Cursor, Copilot, Cline).

Designed from the ground up for maximum token efficiency, it replaces chatty micro-iterations with single-pass workbook construction—saving over 90% of model tokens and conversational turns.

Key Architectural Highlights

• Single-Pass Workbook Builder: Create complete, multi-sheet, publication-ready workbooks (title banners, table headers, alternating row colors, accounting borders, auto-calculated totals, currency formatting, and native charts) in one single MCP call (excel_build_workbook).
• Visual Design Presets: Built-in typography and visual standards (corporate, financial, modern, compact).
• Lightweight Outline Inspection: Extract sheet names, populated dimensions (A1:H50), column headers, and formula summaries without dumping massive cell grids (excel_get_workbook_outline), saving thousands of context tokens.
• Batch Data Ingestion: Append or overwrite 2D matrices of values into existing sheets in a single atomic operation (excel_batch_write_data).
• Formula & Analytics Engine: Apply validated formulas (SUM, AVERAGE, VLOOKUP), generate native bar/line/pie charts, and build analytical pivot tables.
• Zero-Install Execution: Instant launch with uvx luiccian-excel-mcp.

Quick Start with uvx (Recommended)

No manual clone or virtual environment management required. You can run the server directly using uv:

# Run with stdio transport (default for AI IDEs)
uvx luiccian-excel-mcp

MCP Client Configuration

1. Claude Desktop

Add this configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "excel-mcp": {
      "command": "uvx",
      "args": ["luiccian-excel-mcp"],
      "env": {
        "MCP_ALLOWED_DIRECTORIES": "/path/to/your/spreadsheets"
      }
    }
  }
}

2. Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "excel-mcp": {
      "command": "uvx",
      "args": ["luiccian-excel-mcp"],
      "env": {
        "MCP_ALLOWED_DIRECTORIES": "${workspaceFolder}"
      }
    }
  }
}

Visual Design Presets

Modular Agent Skills

The repository includes pre-built agent skills under skills/:

• excel-tools-reference: Authoritative encyclopedia and decision matrix covering all 33 canonical tools, types, signatures, and safety rules.
• excel-spreadsheet-creator: Direct single-pass synthesis for reports, budgets, and financial statements (excel_build_workbook).
• excel-spreadsheet-editor: Lightweight structural inspection, atomic batch matrix writes, row appending, table formatting, and in-place sorting.
• excel-spreadsheet-analyzer: Context-efficient sampling, statistical column profiling (excel_profile_sheet), and cell discovery (excel_find_cells).

Tool Taxonomy

All tools use the standard excel_* canonical prefix. Legacy unprefixed aliases can optionally be enabled via EXCEL_MCP_LEGACY_ALIASES=1. For complete signatures and parameter schemas, see docs/TOOLS.md.

Security

• Restricted Directories: Access is strictly limited to paths listed in MCP_ALLOWED_DIRECTORIES (or DIRECTORY).
• Formula Sanitization: Formula inputs are validated to avoid dangerous injection patterns.
• Trusted Publishing: Automated PyPI releases use GitHub Actions OIDC and PEP 740 artifact attestation.

Development

# Clone the repository
git clone https://github.com/LuiccianDev/excel-mcp.git
cd excel-mcp

# Install dependencies with Astral uv
uv sync --all-groups

# Run linting and formatting
uv run ruff check .
uv run ruff format --check .

# Run static type checking
uv run mypy src

# Run test suite with coverage gate (80% minimum)
uv run pytest --cov --cov-report=term-missing

# Build the wheel and source distribution
uv run python -m build

Performance Baseline

The repository keeps deterministic workbook-operation benchmarks in tests/benchmarks/test_workbook_benchmarks.py. The initial local baseline is recorded in docs/benchmarks/workbook-baseline.json. Run the benchmark tests before changing batch writes, workbook construction, or format-and-save behavior; do not accept an optimization without comparing the functional result, runtime, and peak memory.

License

This project is licensed under the Apache License 2.0.