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-spreadsheet-creator: Direct single-pass synthesis for reports, budgets, and financial statements.
• excel-spreadsheet-editor: Lightweight structural inspection, atomic batch matrix writes, formatting, and pivot tables.
• excel-spreadsheet-analyzer: Context-efficient sampling, formula verification, and structural auditing.

Tool Taxonomy

All tools support both canonical excel_ prefixes and legacy names for 100% backward compatibility:

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
uv run ruff check src

# Run test suite
uv run pytest

License

This project is licensed under the MIT License.