MCP Excel Server

A Model Context Protocol (MCP) server for Excel file manipulation. Read, write, analyze, and transform Excel spreadsheets (.xlsx) using AI agents.

Features

• Read Data - Extract values, ranges, and metadata from Excel files
• Write Data - Create and modify spreadsheets programmatically
• Formulas - Add Excel formulas for calculations
• Analysis - Statistical summaries, filtering, and grouping
• Charts - Create and modify Excel charts (coming soon)
• Tables - Work with Excel structured tables (coming soon)

Quick Start

Installation

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

# Install with Poetry
poetry install

# Or with pip
pip install -e .

Configuration

# Copy environment template
cp .env.example .env

# Edit .env with your settings
# MCP_EXCEL_TRANSPORT=stdio
# MCP_EXCEL_CACHE_SIZE=5

Running the Server

# Using Poetry
poetry run python -m mcp_excel.server

# Or directly
python -m mcp_excel.server

Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

VS Code / Cursor

Add to .vscode/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "excel": {
      "command": "python",
      "args": ["-m", "mcp_excel.server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

OpenCode

Add to your OpenCode configuration:

{
  "mcpServers": {
    "excel": {
      "command": "python",
      "args": ["-m", "mcp_excel.server"],
      "env": {
        "MCP_EXCEL_TRANSPORT": "stdio"
      }
    }
  }
}

Available Tools

Reading Data

Tool	Description
read_cell	Read a single cell value
read_range	Read a range of cells
get_sheet_info	Get worksheet metadata
search_cells	Search for values
list_sheets	List all worksheets
describe_workbook	Get workbook overview

Writing Data

Tool	Description
write_cells	Write values to cells
write_formula	Add Excel formulas
create_sheet	Create new worksheet

Analysis

Tool	Description
get_column_stats	Statistical summary
filter_rows	Filter data by conditions
group_by	Group and aggregate data

Example Usage

Read Sales Data

User: Read the sales data from C:/reports/Q1.xlsx

Agent calls:
1. describe_workbook(file_path="C:/reports/Q1.xlsx")
2. list_sheets(file_path="C:/reports/Q1.xlsx")
3. read_range(file_path="C:/reports/Q1.xlsx", sheet_name="Sales", range="A1:F100")

Create Summary Report

User: Create a monthly summary with totals

Agent calls:
1. create_sheet(file_path="report.xlsx", sheet_name="Summary")
2. write_cells(file_path="report.xlsx", sheet_name="Summary", range="A1:D1", values=[["Month", "Sales", "Cost", "Profit"]])
3. write_formula(file_path="report.xlsx", sheet_name="Summary", cell="D2", formula="=B2-C2")

Analyze Data

User: Analyze customer demographics

Agent calls:
1. get_column_stats(file_path="customers.xlsx", sheet_name="Data", column="Age")
2. group_by(file_path="customers.xlsx", sheet_name="Data", columns=["Region"], agg_column="Revenue", agg_func="sum")
3. filter_rows(file_path="customers.xlsx", sheet_name="Data", filters=[{"column": "Status", "operator": "==", "value": "Active"}])

Skills

This server includes agent skills for better interaction:

• excel-reading - Guide for reading Excel files
• excel-writing - Guide for writing to Excel files
• excel-analysis - Guide for data analysis
• excel-formulas - Guide for Excel formulas

See the skills/ directory for detailed documentation.

Development

Setup

# Install development dependencies
poetry install --with dev

# Run tests
poetry run pytest

# Run linting
poetry run ruff check src/

# Run type checking
poetry run mypy src/

Project Structure

mcp-excel-server/
├── src/mcp_excel/           # Source code
│   ├── server.py           # MCP server entry point
│   ├── config.py           # Configuration
│   ├── backends/           # Excel backends
│   ├── tools/              # MCP tools
│   ├── resources/          # MCP resources
│   ├── prompts/            # MCP prompts
│   └── utils/              # Utilities
├── tests/                  # Test suite
├── skills/                 # Agent skills
├── examples/               # Usage examples
└── docs/                   # Documentation

Adding New Tools

1. Create tool in src/mcp_excel/tools/
2. Add Pydantic models for input/output
3. Register in server.py
4. Add tests in tests/
5. Update documentation

Troubleshooting

Common Issues

File not found error:

• Ensure you're using absolute paths
• Check file exists and is accessible

Permission denied:

• Close Excel if file is open
• Check file permissions

Memory errors:

• Use pagination for large files
• Reduce cache size in .env

See docs/TROUBLESHOOTING.md for more details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request

License

MIT License - see LICENSE for details.

Acknowledgments

• Model Context Protocol - The standard for AI-tool integration
• FastMCP - Python MCP framework
• openpyxl - Excel file handling