kousunh/Excel-mcp-server

A comprehensive Model Context Protocol (MCP) server for Microsoft Excel operations. Enables AI assistants to perform data analysis, cell editing, formatting, border styling, VBA execution, and complete worksheet management through a structured workflow.

Key Features

Prioritized Workflow Tools

• Step 1: essential_inspect_excel_data - MANDATORY first step for understanding data structure
• Final Step: essential_check_excel_format - MANDATORY final verification of layout and formatting

Advanced Excel Operations

• Data Analysis & Reading - Comprehensive sheet analysis with statistics
• Cell Editing - Single cell or range editing with array support
• Formatting Control - Font colors, background colors, text styles, alignment
• Border Management - Complete border styling with multiple styles and colors
• VBA Execution - Simplified and stable VBA code execution
• Workbook Management - Multi-workbook handling and navigation

Requirements

• Windows OS (Required for COM integration)
• Microsoft Excel installed and running
• Node.js 18 or higher
• Python 3.8 or higher

Installation

1. Clone the repository

git clone https://github.com/kousunh/excel-mcp-server.git
cd excel-mcp-server

2. Run setup script

The setup script will create a Python virtual environment and install all dependencies.

Windows (Command Prompt):

setup.bat

Windows (PowerShell):

.\setup.bat

Linux/Mac (WSL):

./setup.sh

3. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "excel-mcp": {
      "command": "node",
      "args": ["C:/path/to/excel-mcp-server/src/index.js"],
      "env": {},
      "cwd": "C:/path/to/excel-mcp-server"
    }
  }
}

4. Configure Cursor

Add to your Cursor settings:

{
  "mcpServers": {
    "Excel-mcp": {
      "command": "node",
      "args": [
        "C:\\path\\to\\excel-mcp-server\\src\\index.js"
      ]
    }
  }
}

Available Tools

Priority Tools (Use in Order)

essential_inspect_excel_data - STEP 1 - ALWAYS USE FIRST

Analyzes Excel data structure and content before any operations. Essential for understanding current state, sheet structure, data types, and content. Works with both open and closed files.

essential_check_excel_format - FINAL STEP - MANDATORY VERIFICATION

Validates layout and formatting after any changes. Use multiple times to check different ranges. If layout/format issues found, fix and re-verify.

Core Operations

edit_cells

Edit single cells or ranges with optimized performance for large data operations.

set_cell_formats

Apply comprehensive formatting to cell ranges including font colors, background colors, bold, italic, underline, font size, font name, and text alignment.

set_cell_borders

Apply detailed border styling to cell ranges. Supports various border styles (thin, thick, medium, double, dotted, dashed) and colors for different positions (top, bottom, left, right, inside, outside).

Utility Tools

get_open_workbooks

Lists all currently open Excel workbooks.

set_active_workbook

Switches between open workbooks.

get_all_sheet_names

Lists all sheets in a workbook.

navigate_to_sheet

Switches to a specific sheet.

get_excel_status

Checks if Excel is running and responsive.

VBA Execution

execute_vba

Executes custom VBA code in Excel. Creates a temporary Sub procedure, executes it, and automatically cleans up. Supports error handling and unique procedure naming to avoid conflicts.

Usage Examples

Basic Workflow

1. "First, analyze the current Excel data structure"
2. "Edit cells A1:C3 with employee data"
3. "Set borders around the data range"
4. "Apply formatting with bold headers and colored backgrounds"
5. "Finally, verify the layout and formatting"

Data Operations

"Analyze the sales data in workbook 'Sales2024.xlsx'"
"Edit range A1:D10 with quarterly sales figures"
"Apply borders to create a table structure"
"Format headers with bold font and blue background"
"Verify the final layout looks correct"

Workflow Best Practices

1. Always start with essential_inspect_excel_data to understand current state
2. Use dedicated tools (edit_cells, set_cell_formats, set_cell_borders) instead of VBA when possible
3. Always end with essential_check_excel_format to confirm changes
4. Use execute_vba for custom VBA logic when standard tools are insufficient
5. Verify multiple ranges if working with large spreadsheets

Troubleshooting

1. Excel not found: Ensure Excel is running with at least one workbook open
2. Tool timeouts: Large operations automatically use extended timeouts (60 seconds)
3. VBA errors: Simplified VBA execution reduces hanging and freezing issues
4. Format verification: Use verification tool multiple times for different ranges
5. Permission errors: Enable "Trust access to the VBA project object model" in Excel Trust Center

Security

• Server operates only on local Excel files
• VBA code runs in temporary modules that are automatically deleted
• Python virtual environment isolates dependencies
• No network access or external file operations

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly with Excel operations
5. Submit a pull request

Version 2.0 Changes:

• Added prioritized workflow tools with clear naming
• Implemented comprehensive formatting and border controls
• Optimized performance for large data operations
• Simplified and stabilized VBA execution
• Added mandatory verification step for quality assurance