*[日本語 README](README_ja.md)*
# Excel MCP Server
A cross-platform MCP server for reading, writing, and formatting Excel files. Works with both open Excel workbooks (live) and closed .xlsx files (no Excel needed).
## Two Modes
- **`workbook`** — Operate on an open Excel workbook in real-time via xlwings
- **`path`** — Edit closed .xlsx files directly using pure Python (preserves images, charts, and all embedded content)
## Tools
| Tool | workbook | path | Required |
|------|:--------:|:----:|----------|
| `get_excel_info` | - | - | (none) |
| `read_cells` | OK | OK | range |
| `write_cells` | OK | OK | range, value |
| `format_cells` | OK | OK | range, format |
| `execute_vba` | OK | - | workbook, code |
## Requirements
- **Node.js** 18+
- **Python** 3.8+
- **xlwings** (for live Excel mode — `pip install xlwings`)
- **Microsoft Excel** (only needed for `workbook` mode and `execute_vba`)
Works on **Windows** and **macOS**. The `path` mode also works on Linux.
## Installation
```bash
git clone https://github.com/kousunh/excel-mcp-server.git
cd excel-mcp-server
npm install
pip install -r scripts/requirements.txt
```
### Configure MCP Client
Add to your MCP client config (Claude Desktop, Cursor, etc.):
```json
{
"mcpServers": {
"excel-mcp": {
"command": "node",
"args": ["/path/to/excel-mcp-server/src/index.js"]
}
}
}
```
To use a specific Python executable, set the `EXCEL_MCP_PYTHON` environment variable:
```json
{
"mcpServers": {
"excel-mcp": {
"command": "node",
"args": ["/path/to/excel-mcp-server/src/index.js"],
"env": {
"EXCEL_MCP_PYTHON": "/path/to/python"
}
}
}
}
```
## Usage
### Closed files (path mode)
```
read_cells path="/data/report.xlsx" range="A1:D20" formats=true
write_cells path="/data/report.xlsx" range="A1:C3" value=[["Name","Age","City"],["Alice",30,"NYC"],["Bob",25,"LA"]]
format_cells path="/data/report.xlsx" range="A1:C1" format={"bold":true,"backgroundColor":"#4472C4","fontColor":"#FFFFFF"}
```
No Excel installation required. Images, charts, and shapes are preserved.
### Open workbooks (workbook mode)
```
get_excel_info
read_cells workbook="Sales.xlsx" range="B2:F10"
write_cells workbook="Sales.xlsx" range="G2" value="=SUM(B2:F2)"
execute_vba workbook="Sales.xlsx" code="Range(\"A1:G10\").AutoFilter"
```
Requires Excel to be running with the workbook open.
## License
MIT
