# Excel Mcp

> A Model Context Protocol (MCP) server for working with Excel (.xlsx) files without requiring Microsoft Excel. Enables AI assistants to create, read, modify, and format spreadsheets using openpyxl, fully in Python and cross-platform.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mort-lab-excel-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mort-lab](https://agentstack.voostack.com/s/mort-lab)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mort-lab](https://github.com/mort-lab)
- **Source:** https://github.com/mort-lab/excel-mcp

## Install

```sh
agentstack add mcp-mort-lab-excel-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Excel MCP Server

A comprehensive [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that enables AI assistants to perform Excel file operations without requiring Microsoft Excel installation.

[](https://smithery.ai/server/@mort-lab/excel-mcp)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](tests/)
[](https://modelcontextprotocol.io)

## Why This Server?

| Feature | Excel MCP Server | Alternatives |
|---------|------------------|--------------|
| **No Excel Required** | ✅ Pure Python (openpyxl) | ❌ Requires MS Office |
| **Cross-Platform** | ✅ Windows, Mac, Linux | ⚠️ Limited |
| **Type Safety** | ✅ Full Pydantic validation | ❌ No validation |
| **Formatting Support** | ✅ Fonts, colors, borders | ⚠️ Basic only |
| **Formula Support** | ✅ Full Excel formulas | ⚠️ Limited |
| **MCP Protocol** | ✅ Native support | ❌ Custom protocols |
| **Remote Deploy** | ✅ Smithery ready | ❌ Local only |

## Features

- **📊 Workbook Management**: Create, open, save Excel workbooks
- **📄 Sheet Operations**: Create, delete, rename, copy worksheets
- **📝 Cell Operations**: Read and write individual cells or ranges
- **🔢 Formula Support**: Write and evaluate Excel formulas
- **🎨 Rich Formatting**: Fonts, colors, borders, alignment, number formats
- **✅ Type-safe** operations with Pydantic validation
- **✅ Well-tested** with 17 tests

## Installation

### 🚀 Smithery (Recommended)

Deploy globally and share with anyone - **no installation required**!

```json
{
  "mcpServers": {
    "excel": {
      "url": "https://server.smithery.ai/@mort-lab/excel-mcp/mcp"
    }
  }
}
```

### 💻 Local Installation

```bash
# Using uvx (recommended)
uvx excel-mcp-server

# Using pip
pip install excel-mcp-server

# From source
git clone https://github.com/mort-lab/excel-mcp
cd excel-mcp
uv sync
```

## Quick Start

Add to your Claude Desktop config:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "excel": {
      "command": "uvx",
      "args": ["excel-mcp-server"]
    }
  }
}
```

Restart Claude Desktop and start using Excel operations!

### Example Usage

```
"Create a new Excel workbook called sales_report.xlsx"
"Write 'Product' to cell A1 in Sheet1"
"Format the header row with bold text and blue background"
"Add a formula in D2 that multiplies B2 and C2"
"Read the data from range A1:D10"
```

## Connect with the Author

[](https://www.linkedin.com/in/martin-areso/)

**Let's connect on LinkedIn!**

I'm **Martin Irurozki**, a fullstack developer passionate about AI automation, building intelligent tools, and creating real-world solutions that make a difference. If you:

- 🚀 Want to discuss MCP servers, AI integrations, and automation
- 💡 Have ideas for new features or real-world use cases
- 🤝 Are interested in collaboration opportunities
- 🛠️ Build tools and solutions with AI
- 🌟 Just want to connect and network with fellow developers

**[Connect with me on LinkedIn →](https://www.linkedin.com/in/martin-areso/)**

I'd love to hear about your projects and how this Excel MCP server is helping you build amazing things!

---

## Available Tools

The server provides **20 MCP tools** across 4 categories:

### Workbook Operations (3 tools)

- `create_workbook(file_path)` - Create a new Excel workbook
- `get_workbook_info(file_path)` - Get workbook metadata
- `list_sheets(file_path)` - List all worksheet names

### Sheet Operations (4 tools)

- `create_sheet(workbook_path, sheet_name, index?)` - Create a new worksheet
- `delete_sheet(workbook_path, sheet_name)` - Delete a worksheet
- `rename_sheet(workbook_path, old_name, new_name)` - Rename a worksheet
- `copy_sheet(workbook_path, source_sheet, new_name)` - Copy a worksheet

### Cell Operations (5 tools)

- `write_cell(workbook_path, sheet_name, cell, value)` - Write to a cell
- `read_cell(workbook_path, sheet_name, cell)` - Read from a cell
- `write_range(workbook_path, sheet_name, start_cell, data)` - Write data to a range
- `read_range(workbook_path, sheet_name, range_ref)` - Read data from a range
- `write_formula(workbook_path, sheet_name, cell, formula)` - Write a formula

### Formatting Operations (8 tools)

- `format_font(...)` - Apply font formatting (bold, italic, color, size)
- `format_fill(...)` - Apply background color
- `format_border(...)` - Apply cell borders
- `format_alignment(...)` - Apply text alignment
- `format_number(...)` - Apply number formatting

## Real-World Use Cases

### 📊 Automated Reporting
Generate monthly sales reports automatically with formatted data, calculations, and professional styling ready to share with stakeholders.

### 📈 Data Analysis
Import and transform data, apply statistical functions (SUM, AVERAGE, STDEV), create summary tables, and export results.

### 🎨 Invoice Generation
Create professional invoices with custom formatting, company branding, automatic calculations, and formula-driven totals.

### 📋 Inventory Management
Track stock levels with real-time updates, conditional formatting for alerts, and automated reorder calculations.

### 📑 Data Migration
Read from old Excel files, clean and transform data, apply new formatting standards, and export to new structure.

## Examples

### Example 1: Formatted Sales Report

Ask Claude:
```
Create a sales report in sales_2024.xlsx with:
1. Headers: Date, Product, Quantity, Price, Total
2. Format headers: Bold, white text, blue background (#4472C4)
3. Add 10 sample sales entries with realistic data
4. Total column formula: =C2*D2 (for each row)
5. Format prices as currency: $#,##0.00
6. Add borders around all cells (thin, black)
7. Center-align all headers
8. Sum total sales in the last row with bold formatting
```

**Result:** Professional report with automatic calculations, fully formatted and ready to share.

### Example 2: Multi-Sheet Workbook

Ask Claude:
```
Create quarterly_report.xlsx with 5 sheets:
- Sheets: Q1, Q2, Q3, Q4, Summary
- Each Q sheet has: Month, Revenue, Expenses, Profit
- Add 3 months of data per quarter
- Profit formula: =B2-C2
- Summary sheet with formulas that sum all quarters
- Format all currency values as $#,##0.00
```

**Result:** Complex multi-sheet workbook with cross-sheet formulas and comprehensive business report.

### Example 3: Data Migration

Ask Claude:
```
Read data from old_data.xlsx sheet 'Sales' range A1:E100,
then create new_data.xlsx with:
- Same data but sorted by date (column A)
- Add a new column F with 10% markup calculation (=E*1.1)
- Format dates as 'mm/dd/yyyy'
- Format currency columns as $#,##0.00
- Add bold headers with blue background
```

**Result:** Clean data migration enhanced with calculations and professional formatting.

## Development

### Setup

```bash
# Clone and install
git clone https://github.com/mort-lab/excel-mcp
cd excel-mcp
uv sync

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=excel_mcp_server

# Lint and format
uv run ruff check
uv run ruff format
```

### Project Structure

```
excel-mcp-server/
├── src/excel_mcp_server/
│   ├── server.py              # FastMCP server (local)
│   ├── server_smithery.py     # Smithery-compatible server
│   ├── models.py              # Pydantic validation models
│   ├── operations/            # Business logic
│   │   ├── workbook.py
│   │   ├── cell.py
│   │   ├── sheet.py
│   │   └── formatting.py
│   └── utils/
│       └── validators.py
├── tests/                     # Test suite (17 tests)
└── pyproject.toml             # Project configuration
```

## Performance

- **Fast**: Handles workbooks up to 10,000 rows efficiently
- **Memory**: ~50MB for typical operations
- **Lightweight**: No Excel installation required

| Operation | Time | Notes |
|-----------|------|-------|
| Create workbook | ~50ms | Empty workbook |
| Write 100 cells | ~200ms | Individual writes |
| Write 100 cells (range) | ~50ms | Bulk operation |
| Read 1000 cells | ~300ms | From existing file |
| Apply formatting | ~100ms | Per range |

## Limitations

- ❌ No chart/graph support (coming soon)
- ❌ No pivot tables (roadmap)
- ❌ No VBA macros (intentional - pure Python)
- ⚠️ File size limit: 100MB recommended

## FAQ

**Can I use this with Google Sheets?**
No, this server works exclusively with Excel (.xlsx) files.

**Does it work offline?**
Yes! When installed locally, it works completely offline.

**What Excel features are supported?**
- ✅ Formulas (SUM, AVERAGE, IF, VLOOKUP, COUNT, etc.)
- ✅ Formatting (fonts, colors, borders, alignment, number formats)
- ✅ Multiple sheets and workbooks
- ✅ Cell ranges and bulk operations
- ✅ Formula references across sheets
- ❌ Charts and graphs (roadmap)
- ❌ Pivot tables (roadmap)
- ❌ Macros/VBA (not planned - security)

**How large can my Excel files be?**
Recommended: Up to 100MB or ~50,000 rows for optimal performance.

**Can I use this in production?**
Yes! The server is tested and stable. Consider using Smithery for deployment and scaling.

## Troubleshooting

**Import Errors**
```bash
uv sync
```

**Permission Errors**
```bash
# Check permissions
ls -la /path/to/directory

# Fix permissions (Unix/Mac)
chmod u+w /path/to/directory
```

**File Already Exists**
When creating a workbook, if the file already exists, the operation will fail. Delete the existing file or use a different filename.

## Contributing

Contributions are welcome! Here's how:

**Development Workflow:**
1. Fork & clone the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Make changes with tests
4. Run tests: `uv run pytest`
5. Run linting: `uv run ruff check`
6. Commit: `git commit -m 'feat: Add amazing feature'`
7. Push & create Pull Request

**Commit Convention:**
We use [Conventional Commits](https://www.conventionalcommits.org/):
- `feat:` New features
- `fix:` Bug fixes
- `docs:` Documentation
- `test:` Adding tests
- `refactor:` Code refactoring

## Roadmap

**v0.2.0 (Next Release)**
- Chart and graph creation
- Data validation rules
- Conditional formatting
- Image insertion

**v0.3.0**
- Pivot table operations
- Cell comments and notes
- Protected sheets
- Named ranges

**v1.0.0**
- CSV import/export
- PDF export
- Template system
- 80%+ test coverage

## Support

- 🐛 **Bug reports**: [GitHub Issues](https://github.com/mort-lab/excel-mcp/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/mort-lab/excel-mcp/discussions)
- 📧 **Email**: m.irurozki@gmail.com

## License

This project is licensed under the MIT License.

## Acknowledgments

- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Excel operations powered by [openpyxl](https://openpyxl.readthedocs.io/)
- Inspired by the [Model Context Protocol](https://modelcontextprotocol.io/)
- Deployed with [Smithery](https://smithery.ai)

---

**Made with ❤️ by [Martin Irurozki](https://github.com/mort-lab)**

*Empowering AI assistants to work with Excel files, one cell at a time.*

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mort-lab](https://github.com/mort-lab)
- **Source:** [mort-lab/excel-mcp](https://github.com/mort-lab/excel-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mort-lab-excel-mcp
- Seller: https://agentstack.voostack.com/s/mort-lab
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.