Excel MCP Server

A powerful Model Context Protocol (MCP) server that enables AI assistants like Claude to work seamlessly with Excel files. Built with TypeScript, ExcelJS, and the official MCP SDK.

About

This MCP server provides 34 comprehensive tools for Excel file manipulation, allowing Claude Desktop and other MCP clients to read, write, format, analyze, and transform Excel spreadsheets programmatically. Whether you need to extract data, create reports, apply complex formatting, or generate pivot tables and charts, this server has you covered.

Perfect for:

• 📊 Automated data analysis and reporting
• 📈 Business intelligence workflows
• 🔄 Data transformation and ETL processes
• 📝 Report generation from templates
• 🎨 Batch formatting and styling

Features

• 34 comprehensive tools for Excel manipulation
• ✨ Real-time Live Editing - See changes instantly in Excel (macOS with Microsoft Excel)
• Full support for reading, writing, formatting, and analyzing Excel files
• NEW: Charts, Pivot Tables, Excel Tables, and Conditional Formatting
• Built with the official MCP SDK
• Type-safe with TypeScript and Zod validation
• Preserves formatting when modifying files
• Optional backup creation before modifications
• Supports both JSON and Markdown response formats

Installation

🚀 Quick Installation (Recommended) - One Click!

The easiest way to install this server is using the pre-built MCPB bundle:

1. Download the latest excel-mcp-server.mcpb file from the releases page
2. Double-click the .mcpb file, or:
   • Open Claude Desktop
   • Go to Settings → Extensions → Advanced Settings
   • Click "Install Extension..."
   • Select the downloaded .mcpb file
3. Restart Claude Desktop
4. Done! No Node.js installation, no config files to edit

Note: One-click installation works on Claude Desktop for macOS and Windows. All dependencies are bundled - no additional setup required!

For more details, see BUNDLE.md.

---

🛠️ Manual Installation (Advanced)

If you prefer to build from source:

Step 1: Clone and build the project

git clone https://github.com/sbraind/excel-mcp-server.git
cd excel-mcp-server
npm install
npm run build

Step 2: Configure Claude Desktop

Add this configuration to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "excel": {
      "command": "node",
      "args": ["${__dirname}/dist/index.js"]
    }
  }
}

Note: When using the MCPB bundle or manual installation, use ${__dirname} which automatically resolves to the server's directory. For manual installations without MCPB, you can also use absolute paths like /path/to/excel-mcp-server/dist/index.js.

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop completely.

Step 4: Verify

The server should now be available in Claude. Try:

Create a new Excel file at ~/Documents/test.xlsx with a sheet called "Sales" containing sample data

For detailed installation instructions and troubleshooting, see INSTALLATION.md.

---

Configuration Options

The server supports several configuration options that can be set through Claude Desktop's MCP configuration:

{
  "mcpServers": {
    "excel": {
      "command": "node",
      "args": ["${__dirname}/dist/index.js"],
      "config": {
        "createBackupByDefault": false,
        "defaultResponseFormat": "json",
        "allowedDirectories": []
      }
    }
  }
}

Available Options:

• createBackupByDefault (boolean, default: false) Automatically create backup files (.backup extension) before modifying Excel files. When enabled, every destructive operation will create a backup unless explicitly disabled in the tool call.

• defaultResponseFormat (string: "json" or "markdown", default: "json") Default format for tool responses. Can be overridden per tool call with the responseFormat parameter.

• allowedDirectories (array of strings, default: []) List of directories where the server is allowed to read/write Excel files. When empty, all directories are accessible. Use this to restrict file access for security:

  "allowedDirectories": [
    "~/Documents/Excel",
    "~/Projects/data"
  ]

  The server will reject any file operations outside these directories.

Input Validation

All tool inputs are validated using Zod schemas. Invalid parameters will return clear error messages indicating what's wrong:

• Cell addresses must match format A1, B2, etc.
• Ranges must match format A1:D10
• File paths are checked against allowedDirectories if configured
• Missing required parameters are reported immediately

---

✨ Real-Time Live Editing (macOS)

The Excel MCP Server features automatic real-time editing for Excel files that are already open in Microsoft Excel on macOS. When a file is open, changes are applied instantly and become visible immediately—no need to close and reopen the file!

How It Works

The server automatically detects when:

1. Microsoft Excel is running on your Mac
2. The target file is open in Excel

When both conditions are met, the server uses AppleScript to modify the open Excel file directly. Otherwise, it falls back to file-based editing using ExcelJS.

Supported Operations (16 Live-Editing Tools)

The following tools support real-time editing when files are open in Excel:

Writing:

• excel_update_cell - Update cell values instantly
• excel_add_row - Add rows and see them appear immediately
• excel_write_range - Write data ranges in real-time
• excel_set_formula - Set formulas that calculate instantly

Formatting:

• excel_format_cell - Apply formatting (fonts, colors, borders) live
• excel_set_column_width - Adjust column widths instantly
• excel_set_row_height - Adjust row heights instantly
• excel_merge_cells - Merge cells in real-time

Sheet Management:

• excel_create_sheet - Create new sheets that appear immediately
• excel_delete_sheet - Delete sheets with instant feedback
• excel_rename_sheet - Rename sheets in real-time

Row/Column Operations:

• excel_delete_rows - Delete rows and see them disappear instantly
• excel_delete_columns - Delete columns in real-time
• excel_insert_rows - Insert rows that appear immediately
• excel_insert_columns - Insert columns instantly

Advanced:

• excel_unmerge_cells - Unmerge cells in real-time

Response Indicators

Tool responses include a method field indicating which approach was used:

{
  "success": true,
  "message": "Cell A1 updated (via Excel)",
  "method": "applescript",
  "note": "Changes are visible immediately in Excel"
}

vs.

{
  "success": true,
  "message": "Cell A1 updated",
  "method": "exceljs",
  "note": "File updated. Open in Excel to see changes."
}

Requirements

• Platform: macOS only (AppleScript is a macOS technology)
• Application: Microsoft Excel for Mac must be installed
• File State: Target Excel file must be open in Excel

Benefits

• Instant Feedback: See changes as they happen—perfect for interactive workflows
• No File Conflicts: Works directly with the open file without save/reload cycles
• Seamless Experience: Automatically falls back to file-based editing when Excel isn't available

Note

Read-only operations (like excel_read_sheet, excel_read_range, etc.) don't require real-time editing as they don't modify files. Complex operations like pivot tables, charts, and conditional formatting use file-based editing for reliability.

---

Quick Start

Once installed, you can start using the server immediately in Claude Desktop. Here are some example prompts:

Create a new Excel file with sales data for Q1 2024

Read the data from Sheet1 in ~/Documents/report.xlsx

Apply bold formatting and blue background to the header row in my sales spreadsheet

Create a pivot table showing total sales by product and month

Generate a column chart from the data in range A1:B10

For more examples and detailed use cases, see FEATURE_SUMMARY.md.

---

Available Tools

📖 Reading (5 tools)

1. excel_read_workbook

List all sheets and metadata of an Excel workbook.

Example:

{
  "filePath": "./data.xlsx",
  "responseFormat": "json"
}

2. excel_read_sheet

Read complete data from a sheet with optional range.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "range": "A1:D10",
  "responseFormat": "markdown"
}

3. excel_read_range

Read a specific range of cells.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "range": "B2:E20",
  "responseFormat": "json"
}

4. excel_get_cell

Read value from a specific cell.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "cellAddress": "A1",
  "responseFormat": "json"
}

5. excel_get_formula

Read the formula from a specific cell.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "cellAddress": "D5",
  "responseFormat": "json"
}

✏️ Writing (5 tools)

6. excel_write_workbook

Create a new Excel file with data.

Example:

{
  "filePath": "./output.xlsx",
  "sheetName": "MyData",
  "data": [
    ["Name", "Age", "City"],
    ["Alice", 30, "New York"],
    ["Bob", 25, "Los Angeles"]
  ],
  "createBackup": false
}

7. excel_update_cell

Update value of a specific cell.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "cellAddress": "B2",
  "value": 1500,
  "createBackup": true
}

8. excel_write_range

Write multiple cells simultaneously.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "range": "A1:C2",
  "data": [
    ["Header1", "Header2", "Header3"],
    [100, 200, 300]
  ],
  "createBackup": false
}

9. excel_add_row

Add a row at the end of the sheet.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "data": ["Product X", 150, "2024-01-15"],
  "createBackup": false
}

10. excel_set_formula

Set or modify a formula in a cell.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "cellAddress": "D2",
  "formula": "SUM(B2:C2)",
  "createBackup": false
}

🎨 Formatting (4 tools)

11. excel_format_cell

Change cell formatting (color, font, borders, alignment).

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "cellAddress": "A1",
  "format": {
    "font": {
      "bold": true,
      "size": 14,
      "color": "FF0000"
    },
    "fill": {
      "type": "pattern",
      "pattern": "solid",
      "fgColor": "FFFF00"
    },
    "alignment": {
      "horizontal": "center",
      "vertical": "middle"
    }
  },
  "createBackup": false
}

12. excel_set_column_width

Adjust width of a column.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "column": "A",
  "width": 20,
  "createBackup": false
}

13. excel_set_row_height

Adjust height of a row.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "row": 1,
  "height": 30,
  "createBackup": false
}

14. excel_merge_cells

Merge cells in a range.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "range": "A1:D1",
  "createBackup": false
}

📑 Sheet Management (4 tools)

15. excel_create_sheet

Create a new sheet in the workbook.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "NewSheet",
  "createBackup": false
}

16. excel_delete_sheet

Delete a sheet from the workbook.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "OldSheet",
  "createBackup": true
}

17. excel_rename_sheet

Rename a sheet.

Example:

{
  "filePath": "./data.xlsx",
  "oldName": "Sheet1",
  "newName": "Sales2024",
  "createBackup": false
}

18. excel_duplicate_sheet

Duplicate a complete sheet.

Example:

{
  "filePath": "./data.xlsx",
  "sourceSheetName": "Template",
  "newSheetName": "January",
  "createBackup": false
}

🔧 Operations (3 tools)

19. excel_delete_rows

Delete specific rows.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "startRow": 5,
  "count": 3,
  "createBackup": true
}

20. excel_delete_columns

Delete specific columns.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "startColumn": "C",
  "count": 2,
  "createBackup": true
}

21. excel_copy_range

Copy range to another location.

Example:

{
  "filePath": "./data.xlsx",
  "sourceSheetName": "Sales",
  "sourceRange": "A1:D10",
  "targetSheetName": "Backup",
  "targetCell": "A1",
  "createBackup": false
}

📊 Analysis (2 tools)

22. excel_search_value

Search for a value in sheet/range.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "searchValue": "Apple",
  "range": "A1:Z100",
  "caseSensitive": false,
  "responseFormat": "markdown"
}

23. excel_filter_rows

Filter rows by condition.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "column": "B",
  "condition": "greater_than",
  "value": 1000,
  "responseFormat": "json"
}

📈 Charts (1 tool)

24. excel_create_chart

Create charts from data ranges.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "chartType": "column",
  "dataRange": "A1:B10",
  "position": "D2",
  "title": "Monthly Sales",
  "showLegend": true,
  "createBackup": false
}

Note: ExcelJS has limited native chart support. This creates a chart placeholder with metadata.

🔄 Pivot Tables (1 tool)

25. excel_create_pivot_table

Create pivot tables for data analysis.

Example:

{
  "filePath": "./data.xlsx",
  "sourceSheetName": "Sales",
  "sourceRange": "A1:D100",
  "targetSheetName": "Pivot",
  "targetCell": "A1",
  "rows": ["Product"],
  "columns": ["Month"],
  "values": [
    { "field": "Amount", "aggregation": "sum" }
  ],
  "createBackup": false
}

📋 Excel Tables (1 tool)

26. excel_create_table

Convert ranges to formatted Excel tables.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Data",
  "range": "A1:D50",
  "tableName": "SalesTable",
  "tableStyle": "TableStyleMedium2",
  "showRowStripes": true,
  "createBackup": false
}

✅ Validation (3 tools)

27. excel_validate_formula_syntax

Validate formula syntax without applying it.

Example:

{
  "formula": "SUM(A1:A10) / COUNT(B1:B10)"
}

28. excel_validate_range

Validate if a range string is valid.

Example:

{
  "range": "A1:Z100"
}

29. excel_get_data_validation_info

Get data validation rules for a cell.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Input",
  "cellAddress": "A1",
  "responseFormat": "json"
}

🔧 Advanced Operations (4 tools)

30. excel_insert_rows

Insert rows at a specific position.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "startRow": 5,
  "count": 3,
  "createBackup": false
}

31. excel_insert_columns

Insert columns at a specific position.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "startColumn": "C",
  "count": 2,
  "createBackup": false
}

32. excel_unmerge_cells

Unmerge previously merged cells.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Report",
  "range": "A1:D1",
  "createBackup": false
}

33. excel_get_merged_cells

List all merged cell ranges in a sheet.

Example:

{
  "filePath": "./data.xlsx",
  "sheetName": "Report",
  "responseFormat": "markdown"
}

🎨 Conditional Formatting (1 tool)

34. excel_apply_conditional_format

Apply conditional formatting to ranges.

Example (Cell Value):

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "range": "B2:B100",
  "ruleType": "cellValue",
  "condition": {
    "operator": "greaterThan",
    "value": 1000
  },
  "style": {
    "fill": {
      "type": "pattern",
      "pattern": "solid",
      "fgColor": "FF00FF00"
    },
    "font": {
      "bold": true
    }
  },
  "createBackup": false
}

Example (Color Scale):

{
  "filePath": "./data.xlsx",
  "sheetName": "Sales",
  "range": "C2:C100",
  "ruleType": "colorScale",
  "colorScale": {
    "minColor": "FFFF0000",
    "maxColor": "FF00FF00"
  },
  "createBackup": false
}

Development

Build

npm run build

Watch mode

npm run watch

Run

npm start

Error Handling

All tools include robust error handling and will return descriptive error messages for:

• File not found
• Sheet not found
• Invalid cell addresses or ranges
• Invalid formatting options
• Write errors

Features

Backup Support

Most write operations support an optional createBackup parameter. When set to true, a backup of the original file will be created with a .backup extension before modifications.

Response Formats

Read operations support both json and markdown response formats:

• JSON: Structured data, ideal for programmatic processing
• Markdown: Human-readable tables and formatted output

Data Preview

When reading large datasets, the markdown format automatically shows a preview of the first 100 rows.

Dependencies

• @modelcontextprotocol/sdk - Official MCP SDK
• exceljs - Excel file manipulation
• zod - Schema validation
• typescript - Type safety

Links & Resources

• Repository: github.com/sbraind/excel-mcp-server
• Issues & Bug Reports: GitHub Issues
• Model Context Protocol: modelcontextprotocol.io
• Claude Desktop: claude.ai
• ExcelJS Documentation: github.com/exceljs/exceljs

License

MIT - See LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support

If you encounter any issues or have questions:

1. Check the Installation Guide for common setup issues
2. Review existing issues to see if your problem has been addressed
3. Open a new issue with detailed information about your problem

---

Built with ❤️ using Claude Code