DOCSEARCHbyAlgolia
Submit Docs

ExcelMcp: MCP Server and CLI for Microsoft Excel Automation

repository·main·Indexed 43 days ago

https://github.com/sbroenne/mcp-server-excel

A Windows-only toolset providing a Model Context Protocol (MCP) server and CLI that enables AI agents to automate Microsoft Excel via its COM API. Supports high-fidelity automation of Power Query, DAX queries, PivotTables, and VBA macros. Compatible with Claude Desktop, Cursor, Cline, Windsurf, and VS Code.

Tokens
255.2K
Snippets
596
Records
1.1K
Agent score
59%

What's inside ExcelMcp

  1. Overview of ExcelMcp Capabilities

    main

    ExcelMcp is a Model Context Protocol (MCP) server that allows AI assistants to control Microsoft Excel via its official COM API. Unlike file-parsing libraries, it drives the actual Excel application, enabling live operations that require the Excel engine.

    Key Capabilities:

    • Live Operations: Refresh Power Query, recalculate workbooks, refresh PivotTables and the Data Model, and evaluate DAX.
    • Advanced Automation: Run VBA macros and Python =PY() code.
    • Direct Manipulation: Edit existing workbooks while keeping formulas, PivotTables, charts, macros, and formatting intact.
    • Visual Feedback: Use the command "Show me Excel while you work" to watch the AI make changes in real time.

    Requirements:

    • OS: Windows only
    • Excel Version: Excel 2016 or newer

  2. Overview of ExcelMcp Capability Areas

    main

    ExcelMcp provides 31 specialized tools and 326 operations categorized into four main capability areas. You can interact with these tools using plain language via an AI assistant, which will select the appropriate tool for your request.

    Capability Areas

    1. Data & Analytics: Focuses on importing, transforming, modeling, and summarizing data. Includes tools for Power Query, Data Model & DAX, Excel Tables, PivotTables, Data Connections, and QueryTables.
    2. Cells & Workbooks: Focuses on reading, writing, and formatting cells, as well as managing formulas, sheets, and files. Includes tools for File Operations, Calculation, Ranges, Worksheets, Workbook, and Named Ranges.
    3. Charts & Visualization: Focuses on building charts, interactive visuals, and capturing workbook screenshots. Includes tools for Charts, Slicers, Conditional Formatting, Screenshots, Drawing Objects, and Sparklines.
    4. Automation & Advanced: Focuses on running VBA or Python, controlling Excel windows, solving What-If scenarios, and working with XML Maps.

  3. Design System Overview: Code Editorial — Frame

    main

    The Code editorial — Frame is a video-first design system optimized for a 1920×1080 (16:9) primary frame. It follows a 'warm-editorial' aesthetic characterized by a three-color trinity: cream (ground), ink (voice), and coral (voltage), with warm navy reserved exclusively for code/terminal surfaces.

    Core Principles

    • Sacred Atoms: Use the provided YAML frontmatter for colors, typography, and components verbatim.
    • Composition: While atoms are fixed, composition is free; frames can be dense or focal.
    • Rationed Coral: Use coral for at most ONE moment per frame (e.g., a single CTA, one inline link, or one full-bleed band). Never use it for headlines or body text.
    • Hairline Elevation: Use a 1px low-alpha ink border or a single soft warm shadow. Avoid heavy drops, glows, or gradients.
    • Typography Voices:
      • Segoe UI: Used for all display (headlines, covers, stats), body text, leads, and UI chrome. Display text should be sentence case with negative tracking.
      • Cascadia Mono: Used for the indexical layer (kickers, technical labels, code windows, status strips). Kickers must be UPPERCASE and prefixed with the coral ✱ mark.

  4. Behavioral Rules for Excel MCP Operations

    main

    When using the Excel MCP server, AI assistants and automation agents should follow specific behavioral guidelines to ensure reliable and professional Excel automation. Key principles include:

    • Immediate Execution: Execute tasks immediately without asking for confirmation or clarification. Use discovery tools (like file(list), table(list), or worksheet(list)) to find information instead of asking the user.
    • Excel Visibility: For multi-step tasks, ask the user if they want Excel visible (Watch me work) or hidden (Work in background). If no response is given, default to hidden.
    • Professional Formatting: Always apply proper column widths, headers, and number formats. Convert tabular data into Excel Tables (ListObjects) rather than plain ranges.
    • Mandatory Text Summaries: Never end a turn with only a tool call. Always provide a text summary of what was accomplished.
    • Session Management: Always close sessions when finished to prevent memory leaks and file locking.

  5. Capabilities and Agent Skills of Excel MCP Server

    main

    The Excel MCP Server (excel-mcp) provides 31 specialized tools with 326 operations. Unlike tools that read/write .xlsx files directly (which can break PivotTables or macros), this server uses the actual Excel engine via COM API to run live operations.

    Core Capabilities:

    • Power Query & M code: Create, edit, optimize, and refresh queries.
    • Power Pivot & DAX: Build Data Models, create DAX measures, and manage relationships.
    • PivotTables & Charts: Create and format PivotTables and PivotCharts.
    • Tables & Ranges: Read/write data, formulas, and formatting; manage Excel Tables.
    • VBA macros: View, import, update, execute, and export VBA code.
    • Worksheets & Connections: Manage sheets, named ranges, and data connections.
    • Python in Excel: Write and run =PY() formulas using pandas and NumPy.
    • Agent Mode: Real-time side-by-side view of AI work in Excel.

    Agent Skills: This extension includes an Agent Skill following the agentskills.io specification. It is registered automatically through VS Code's chatSkills contribution point and provides domain-specific guidance for AI assistants.

  6. Capabilities of Excel MCP Server

    main

    The Excel MCP Server provides 31 tools with 326 operations to automate Microsoft Excel through natural language. Key capabilities include:

    • Create & Edit: Build spreadsheets, tables, and formulas.
    • Analyze Data: Create PivotTables, charts, and perform DAX calculations.
    • Transform Data: Use Power Query for imports and transformations.
    • Format & Style: Apply conditional formatting, number formats, and table styles.
    • Automate: Run VBA macros, perform batch operations, and refresh data.
    • Agent Mode: Real-time visualization of Excel operations side-by-side with Claude.

  8. Determine if ExcelMcp is right for your use case

    main

    Recommended Users

    • Data analysts automating repetitive Excel workflows.
    • Developers building Excel-based data solutions.
    • Business users managing complex workbooks.
    • Teams maintaining Power Query, VBA, and DAX code in version control.

    Limitations & Non-Target Use Cases

    • Platform: Not designed for Linux or macOS environments (requires Windows/Microsoft Excel).
    • Environment: Not for server-side processing without an interactive desktop.
    • High-Volume Processing: For high-volume, Excel-free batch processing, use libraries like ClosedXML or EPPlus instead of ExcelMcp.

  9. Supported Excel features via Excel MCP

    main

    Excel MCP Server provides access to the full suite of Microsoft Excel's professional features, allowing an AI assistant to automate:

    • Power Query: Automate data preparation, cleaning, and shaping through repeatable queries.
    • Data Model & DAX: Define business logic once using DAX (Data Analysis Expressions) and reuse it across the workbook's data model.
    • PivotTables & Charts: Build native Excel objects for data visualization and analysis.
    • VBA Workflows: Execute existing VBA modules and macros (using your existing user permissions).
    • Python in Excel: Run Python analysis directly within the workbook (requires a supported subscription and internet access as Python runs in Microsoft's cloud).
    • Real Calculation: Trigger the native Excel calculation engine so that changing an input updates all dependent formulas, queries, and charts.

  10. Choose an entry point: MCP Server vs CLI

    main

    ExcelMcp provides two independent entry points depending on your use case:

    • MCP Server (excel-mcp): Best for AI assistants and conversational AI (e.g., Claude Desktop, GitHub Copilot, Cursor, Windsurf). It provides rich tool schemas for AI interaction.
    • CLI (excel-cli): Best for scripting, RPA, CI/CD pipelines, and coding agents that require token-efficient workflows.

    Requirements:

    • OS: Windows
    • Software: Microsoft Excel 2016 or newer
    • Note: No .NET runtime is required for standalone .exe distributions.

  11. Explore the Excel Automation Reference

    main

    The Excel Automation Reference is a specialized corpus designed for AI agents to understand the actual behavior of Microsoft Excel (including COM behavior, Power Query, and DAX) rather than just its theoretical documentation. It is used to guide agent skills and MCP prompts to ensure reliable automation.

    To effectively use this project for automation, you should consult the following categories of reference material:

    Agent Workflow & Safety

    • Key Constraints & Sequencing: Understand the required order of operations (e.g., what must happen before a specific task can be performed).
    • Behavioral Rules: Learn about verification steps and safety protocols for destructive operations.
    • Anti-Patterns to Avoid: Identify common automation mistakes and the recommended correct approaches.
    • Gotchas & Known Limits: Understand surprising Excel behaviors and available workarounds.
    • Agent Mode in Excel: Guidance on observing an agent driving the visible Excel window.

    Workbook & Data Structure

    • Workbook & Worksheet Operations: Managing the lifecycle of workbooks, sheets, and window management.
    • Ranges & Formatting: Handling cell ranges, number formats, and visual styling.
    • Excel Tables: Working with structured Excel Tables.

    Data Modeling & Advanced Analysis

    • Power Query & M Code: Automating data ingestion using Power Query and the M language syntax.
    • Data Model & DAX: Interacting with the Excel Data Model and writing DAX queries.
    • PivotTables & QueryTables: Managing and automating pivot and query tables.
    • Analysis Tools: Using What-If Analysis and XML Maps.

    Visuals & Reporting

    • Charts & Drawing Objects: Automating the creation of charts and other drawing objects.
    • Conditional Formatting & Slicers: Managing dynamic visual rules and slicer controls.
    • Dashboards & Screenshots: Building reports and using screenshots for visual verification of automation results.

  12. Understand ExcelMcp PIA Coverage and Limitations

    main

    ExcelMcp is built using a 'PIA-first' approach, meaning it prioritizes using the official Microsoft.Office.Interop.Excel Primary Interop Assembly (PIA) for type safety.

    What this means for you:

    • Core Excel features (Workbooks, Worksheets, Ranges, PivotTables, Sparklines, etc.) are fully typed and reliable.
    • Data Model features (ModelTables, ModelRelationships, ModelMeasures) are fully typed.
    • Some features use 'dynamic' binding due to technical limitations in the Excel PIA or because they belong to external COM models (like VBA or ADO). This is not a bug, but a design choice to maintain a self-contained deployment without requiring extra dependencies like office.dll or vbe7.dll.