excel-mcp

Excel MCP Server Skill

Provides 232 Excel operations via Model Context Protocol. The MCP Server hosts the ExcelMCP Service in-process and calls it directly for low-latency Excel automation. Tools are auto-discovered - this documents quirks, workflows, and gotchas.

Workflow Checklist

Preconditions

• Windows host with Microsoft Excel installed (2016+)
• Use full Windows paths: C:\Users\Name\Documents\Report.xlsx
• Excel files must not be open in another Excel instance

Calculation Mode Workflow (Batch Performance)

Use calculation_mode for bulk write performance optimization. When writing many values or formulas, disable auto-recalc to avoid recalculating after every cell:

1. calculation_mode(action: 'set-mode', mode: 'manual')  → Disable auto-recalc
2. Perform all writes (range set-values, set-formulas)
3. calculation_mode(action: 'calculate', scope: 'workbook')  → Recalculate once
4. calculation_mode(action: 'set-mode', mode: 'automatic')  → Restore default

Note: You do NOT need manual mode to read formulas - range get-formulas returns formula text regardless of calculation mode.

CRITICAL: Execution Rules (MUST FOLLOW)

Rule 1: NEVER Ask Clarifying Questions

STOP. If you're about to ask "Which file?", "What table?", "Where should I put this?" - DON'T.

You have tools to answer your own questions. USE THEM.

Rule 2: Always End With a Text Summary

NEVER end your turn with only a tool call. After completing all operations, always provide a brief text message confirming what was done. Silent tool-call-only responses are incomplete.

Rule 3: Format Data Professionally

Always apply number formats after setting values:

Workflow:

1. range set-values (data is now in cells)
2. range set-number-format (apply format)

Rule 4: Use Excel Tables (Not Plain Ranges)

Always convert tabular data to Excel Tables:

1. range set-values (write data including headers)
2. table create tableName="SalesData" rangeAddress="A1:D100"

Why: Structured references, auto-expand, required for Data Model/DAX.

Rule 5: Session Lifecycle

1. file(action: 'open', path: '...')  → sessionId
2. All operations use sessionId
3. file(action: 'close', save: true)  → saves and closes

Unclosed sessions leave Excel processes running, locking files.

Rule 6: Data Model Prerequisites

DAX operations require tables in the Data Model:

Step 1: Create table → Table exists
Step 2: table(action: 'add-to-datamodel') → Table in Data Model
Step 3: datamodel(action: 'create-measure') → NOW this works

Rule 7: Power Query Development Lifecycle

BEST PRACTICE: Test-First Workflow

1. powerquery(action: 'evaluate', mCode: '...') → Test WITHOUT persisting
2. powerquery(action: 'create', ...) → Store validated query
3. powerquery(action: 'refresh', ...) → Load data

Why evaluate first:

• Catches syntax errors and missing sources BEFORE creating permanent queries
• Better error messages than COM exceptions from create/update
• See actual data preview (columns + sample rows)
• No cleanup needed - like a REPL for M code
• Skip only for trivial literal tables

Common mistake: Creating/updating without evaluate → pollutes workbook with broken queries

Rule 8: Targeted Updates Over Delete-Rebuild

• Prefer: set-values on specific range (e.g., A5:C5 for row 5)
• Avoid: Deleting and recreating entire structures

Why: Preserves formatting, formulas, and references.

Rule 9: Follow suggestedNextActions

Error responses include actionable hints:

{
  "success": false,
  "errorMessage": "Table 'Sales' not found in Data Model",
  "suggestedNextActions": ["table(action: 'add-to-data-model', tableName: 'Sales')"]
}

Tool Selection Quick Reference

Reference Documentation

See references/ for detailed guidance:

• Core execution rules and LLM guidelines
• Common mistakes to avoid
• Bulk write performance optimization
• Data Model constraints and patterns
• Charts and formatting
• Conditional formatting operations
• Dashboard and report best practices
• Data Model/DAX specifics
• DMV query reference for Data Model analysis
• Excel agent mode and advanced automation
• Gotchas and known limits
• Power Query M code syntax reference
• PivotTable operations
• Power Query specifics
• Range operations and number formats
• Screenshot and visual verification
• Slicer operations
• Table operations
• Window and visibility operations
• Worksheet operations