# Excel MCP Integration Guide

**Last Updated:** 2026-03-08

## Overview

Excel MCP (Model Context Protocol) provides read/write capabilities for Excel files, enabling AI agents to inspect formulas, structure, formatting, and data validation without opening Excel manually. This guide explains how to integrate Excel MCP into the Excel template generation workflow for enhanced debugging and validation.

## Key Principle

**Excel MCP is for inspection/debugging, not template generation.**

- **Production generation:** Continue using PhpSpreadsheet (PHP) - this is our production code path
- **Inspection/debugging:** Use Excel MCP for AI-assisted inspection when validation scripts find issues or for detailed inspection

## Excel MCP Capabilities

Based on the Excel MCP server (haris-musa/excel-mcp-server), Excel MCP provides:

### Core Tools

- **`read_data_from_excel`** - Read cell values, formulas, data validation rules from Excel files
  - Parameters: `filepath`, `sheet_name`, `start_cell`, `end_cell`, `preview`
  - Returns: Structured data with cell values, addresses, and validation rules in JSON format

- **`write_data_to_excel`** - Write structured data to Excel worksheets
  - Parameters: `filepath`, `sheet_name`, `data`, `start_cell` (default: A1)
  - Use: For testing/debugging only, not production template generation

- **`apply_formula`** - Apply Excel formulas to cells
  - Use: For testing/debugging only, not production template generation

### Additional Capabilities

- Data manipulation with formulas and formatting
- Font styling, colors, borders, and conditional formatting
- Chart creation (line, bar, pie, scatter types)
- Pivot table generation
- Excel table creation and management
- Data validation for ranges and formulas
- Worksheet copying, renaming, and deletion

## When to Use Excel MCP

### Use Excel MCP When:

1. **Corruption Diagnosis:** When `validate-generated-xlsx.py` or `inspect-xlsx-structure.py` finds issues, use Excel MCP to inspect the actual file structure
2. **Formula Verification:** Read formulas from cells to verify they match template definition
3. **Structure Validation:** Verify sheet names, named ranges, data validation rules are correctly applied
4. **Quality Checks:** Verify conditional formatting, charts, styling match expected output
5. **Template Comparison:** Compare generated template against expected structure or competitor templates

### When NOT to Use Excel MCP:

1. **Template Generation:** Continue using PhpSpreadsheet (production code path)
2. **Batch Validation:** Continue using Python/PHP scripts for automated validation
3. **CI/CD Pipelines:** Use existing scripts for automated testing

## Integration with Existing Validation Tools

### Validation Tool Hierarchy

1. **Primary Validation (Automated):**
   - `validate-generated-xlsx.py` - Validates ZIP structure, chart XML, XML parse errors
   - `validate-template-excel-quality.php` - Quality checks (formulas, data validation, conditional formatting, styling)

2. **Secondary Inspection (When Issues Found):**
   - `inspect-xlsx-structure.py` - Detailed inspection for corruption diagnosis
   - **Excel MCP** - AI-assisted inspection of formulas, structure, data validation

3. **Final Verification (Before Deploy):**
   - Manual opening in Excel/LibreOffice - Visual inspection for repair prompts

### Workflow Integration

```
Template Generation (PhpSpreadsheet)
    ↓
Automated Validation (Python/PHP scripts)
    ↓
[If Issues Found] → Excel MCP Inspection
    ↓
Manual Verification (Excel/LibreOffice)
    ↓
Deploy
```

## Excel MCP vs Existing Validation Tools

| Tool | Purpose | When to Use |
|------|---------|-------------|
| **Python/PHP Scripts** | Automated validation, CI/CD, batch checks | Primary validation mechanism |
| **Excel MCP** | Inspection/debugging, formula verification, structure checks | When scripts find issues or for detailed inspection |
| **Manual Excel/LibreOffice** | Final verification, visual inspection | Before deploy to check for repair prompts |

## Example Workflows

### 1. Corruption Diagnosis Workflow

**Scenario:** `validate-generated-xlsx.py` found issues with a template

**Steps:**
1. Run Python validation script: `python3 v2/scripts/dev-helpers/validate-generated-xlsx.py`
2. If issues found, inspect structure: `python3 v2/scripts/dev-helpers/inspect-xlsx-structure.py path/to/file.xlsx`
3. Use Excel MCP for detailed inspection:
   ```
   Use Excel MCP to inspect v2/systems/excel-template-generator/output/generated-templates/compliance-checkliste-vorlage.xlsx
   ```
4. Read formulas to verify they're correct:
   ```
   Use Excel MCP to read formulas from v2/systems/excel-template-generator/output/generated-templates/compliance-checkliste-vorlage.xlsx
   ```

### 2. Formula Verification Workflow

**Scenario:** Need to verify formulas match template definition

**Steps:**
1. Generate template: `php v2/systems/excel-template-generator/scripts/template-cli.php generate template.json output.xlsx`
2. Use Excel MCP to read formulas:
   ```
   Use Excel MCP to read formulas from output.xlsx and compare against template definition
   ```
3. Verify formula syntax and cell references match expected values

### 3. Structure Validation Workflow

**Scenario:** Need to verify data validation rules and conditional formatting

**Steps:**
1. Generate template
2. Run quality validation: `php v2/scripts/templates/validate-template-excel-quality.php --template=slug`
3. Use Excel MCP for detailed structure check:
   ```
   Use Excel MCP to inspect the structure of v2/systems/excel-template-generator/output/generated-templates/schichtplan-excel-vorlage.xlsx and verify data validation rules
   ```

## Best Practices

### 1. Enable Excel MCP Per Project

Excel MCP should be enabled "per project" when debugging templates (see `docs/development/MCP_INTEGRATION.md`). Disable when not needed to avoid tool limit issues.

### 2. Use Excel MCP as Complement, Not Replacement

Excel MCP complements existing Python/PHP validation scripts. Continue using scripts for automated validation and CI/CD.

### 3. Document Excel MCP Findings

When using Excel MCP to diagnose issues, document findings in:
- Issue reports
- Template definition updates
- Validation script improvements

### 4. Verify Excel MCP Results

Cross-reference Excel MCP findings with Python/PHP validation scripts to ensure accuracy.

## Tool Availability

Excel MCP is configured in `.cursor/mcp.json`:

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

**Verification:** Excel MCP should appear in Cursor Settings → Tools & MCP when enabled.

## Troubleshooting

### Excel MCP Not Available

1. Check `.cursor/mcp.json` exists and contains Excel MCP configuration
2. Restart Cursor after config changes
3. Verify Excel MCP appears in Settings → Tools & MCP

### Excel MCP Tools Not Working

1. Verify Excel file path is correct and file exists
2. Check file permissions (read access required)
3. Ensure Excel file is valid XLSX format

### Tool Limit Issues

If tools become unresponsive:
1. Disable Excel MCP when not debugging templates
2. Excel MCP adds ~15 tools (within 40-tool threshold when enabled per project)
3. See `docs/development/MCP_INTEGRATION.md` for tool limit guidance

## References

- [EXCEL_TEMPLATE_BEST_PRACTICES.md](EXCEL_TEMPLATE_BEST_PRACTICES.md) – Best practices
- [EXCEL_MCP_EXAMPLES.md](EXCEL_MCP_EXAMPLES.md) – Detailed usage examples
- [MCP_INTEGRATION.md](../../development/MCP_INTEGRATION.md) – MCP integration guide
- [excel-template-integrity.mdc](../../../.cursor/rules/excel-template-integrity.mdc) – Cursor rules
- [Excel MCP Server GitHub](https://github.com/haris-musa/excel-mcp-server) – Excel MCP server documentation