Installation Guide

Complete installation instructions for Excel MCP Server - VS Code Extension, MCP Server, and CLI tool

System Requirements

Required

.NET runtime is NOT required for any installation method — all distributions are self-contained.

Optional (for specific features)

Use this order to avoid setup confusion:

  1. Choose one primary setup path:
    • VS Code Extension (GitHub Copilot users) — auto-configures everything
    • Claude Desktop MCPB — one-click MCP installation
    • GitHub Copilot Plugins (Copilot CLI users) — marketplace installation
    • Manual MCP setup (other MCP clients like Cursor, Windsurf)
  2. Validate MCP setup (run the quick test prompt in Step 4 of manual setup, or test in your client after extension/MCPB/plugin install)
  3. Optional: install CLI (excelcli) for scripting/RPA
  4. Optional: install agent skills separately for non-extension environments

GitHub Copilot Plugins

Best for: GitHub Copilot CLI users who want plugin marketplace installation

copilot plugin marketplace add sbroenne/mcp-server-excel-plugins

copilot plugin install excel-mcp@mcp-server-excel-plugins      # For conversational AI
copilot plugin install excel-cli@mcp-server-excel-plugins      # For scripting / coding agents

Note: After each release, there may be a short delay before plugins appear in the marketplace.

VS Code Extension (Easiest - One-Click Setup)

  1. Install the Extension
    • Open VS Code
    • Press Ctrl+Shift+X (Extensions)
    • Search for “ExcelMcp”
    • Click Install
  2. That’s It!
    • Bundles self-contained MCP server and CLI (no .NET runtime needed)
    • Auto-configures GitHub Copilot
    • Registers agent skills (excel-mcp + excel-cli) via chatSkills
    • Shows quick start guide on first launch

Marketplace Link: Excel MCP VS Code Extension

Claude Desktop (One-Click Install)

Best for: Claude Desktop users who want the simplest installation

  1. Download excel-mcp-{version}.mcpb from the latest release
  2. Double-click the .mcpb file (or drag-and-drop onto Claude Desktop)
  3. Restart Claude Desktop

That’s it! The MCPB bundle includes everything needed - no .NET installation required.

Manual MCP Setup (All MCP Clients)

Best for: Other MCP clients (Cursor, Windsurf, Cline, Claude Code, Codex), advanced users

Step 1: Download MCP Server

  1. Go to the latest release
  2. Download ExcelMcp-MCP-Server-{version}-windows.zip
  3. Extract the ZIP to a permanent location (e.g., C:\Tools\ExcelMcp\)
Expand-Archive "ExcelMcp-MCP-Server-1.x.x-windows.zip" -DestinationPath "C:\Tools\ExcelMcp"

The ZIP contains mcp-excel.exe — a fully self-contained executable (no .NET runtime needed).

To use mcp-excel as a command without specifying the full path:

$toolsDir = "C:\Tools\ExcelMcp"
$userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
if ($userPath -notlike "*$toolsDir*") {
    [Environment]::SetEnvironmentVariable("PATH", "$userPath;$toolsDir", "User")
    Write-Host "Added $toolsDir to user PATH. Restart your terminal to apply."
}

Or manually: Settings → System → About → Advanced system settings → Environment Variables → User variables → Path → Edit → New → add C:\Tools\ExcelMcp

Step 3: Configure Your MCP Client

Use add-mcp to configure all detected coding agents with a single command:

npx add-mcp "mcp-excel" --name excel-mcp

This auto-detects and configures Cursor, VS Code, Claude Code, Claude Desktop, Codex, Zed, Gemini CLI, and more. Use flags to customize:

npx add-mcp "mcp-excel" --name excel-mcp -a cursor -a claude-code

npx add-mcp "mcp-excel" --name excel-mcp -g

npx add-mcp "mcp-excel" --name excel-mcp --all -y

Requires: Node.js for npx. Install with winget install OpenJS.NodeJS.LTS if not already available. No permanent add-mcp installation needed — npx downloads, runs, and cleans up automatically.

Note: If mcp-excel is not on your PATH, use the full path instead: npx add-mcp "C:\Tools\ExcelMcp\mcp-excel.exe" --name excel-mcp

Option B: Manual Configuration

Quick Start: Ready-to-use config files for all clients are available in examples/mcp-configs/

For GitHub Copilot (VS Code):

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "excel-mcp": {
      "command": "mcp-excel"
    }
  }
}

If mcp-excel is not on PATH, use the full path: "command": "C:\\Tools\\ExcelMcp\\mcp-excel.exe"

For GitHub Copilot (Visual Studio):

Create .mcp.json in your solution directory or %USERPROFILE%\.mcp.json:

{
  "servers": {
    "excel-mcp": {
      "command": "mcp-excel"
    }
  }
}

For Claude Desktop:

  1. Locate config file: %APPDATA%\Claude\claude_desktop_config.json
  2. If file doesn’t exist, create it with the content below
  3. If file exists, merge the excel-mcp entry into your existing mcpServers section
{
  "mcpServers": {
    "excel-mcp": {
      "command": "mcp-excel",
      "args": [],
      "env": {}
    }
  }
}
  1. Save and restart Claude Desktop

For Cursor:

  1. Open Cursor Settings (Ctrl+,)
  2. Search for “MCP” in settings
  3. Click “Edit in settings.json” or create config at: %APPDATA%\Cursor\User\globalStorage\mcp\mcp.json
  4. Add this configuration:
{
  "mcpServers": {
    "excel-mcp": {
      "command": "mcp-excel",
      "args": [],
      "env": {}
    }
  }
}
  1. Save and restart Cursor

For Cline (VS Code Extension):

  1. Install Cline extension in VS Code
  2. Open Cline panel and click the MCP settings gear icon
  3. Add this configuration:
{
  "mcpServers": {
    "excel-mcp": {
      "command": "mcp-excel",
      "args": [],
      "env": {}
    }
  }
}
  1. Save and restart VS Code

For Windsurf:

  1. Open Windsurf Settings
  2. Navigate to MCP Servers configuration
  3. Add this configuration:
{
  "mcpServers": {
    "excel-mcp": {
      "command": "mcp-excel",
      "args": [],
      "env": {}
    }
  }
}
  1. Save and restart Windsurf

Step 4: Validate MCP Setup

Restart your MCP client, then ask:

Create an empty Excel file called "test.xlsx"

If it works, you’re all set! 🎉

💡 Tip: Want to watch the AI work? Ask:

Show me Excel while you work on test.xlsx

This opens Excel visibly so you can see every change in real-time - great for debugging and demos!

Optional: CLI Installation (No AI Required)

Best for: Scripting, RPA, CI/CD pipelines, automation without AI

The excelcli.exe tool is already included when you install the excel-cli GitHub Copilot plugin or the VS Code extension. Plain skill-only installs still need the CLI available separately.

If Not Already Installed Via Plugin or VS Code Extension

Download and extract the standalone CLI:

  1. Go to the latest release
  2. Download ExcelMcp-CLI-{version}-windows.zip
  3. Extract to a permanent location (e.g., C:\Tools\ExcelMcp\)
Expand-Archive "ExcelMcp-CLI-1.x.x-windows.zip" -DestinationPath "C:\Tools\ExcelMcp"

Add CLI to PATH

$toolsDir = "C:\Tools\ExcelMcp"
$userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
if ($userPath -notlike "*$toolsDir*") {
    [Environment]::SetEnvironmentVariable("PATH", "$userPath;$toolsDir", "User")
    Write-Host "Added $toolsDir to user PATH. Restart your terminal to apply."
}

Quick Test

excelcli --version
excelcli --help

excelcli -q session open test.xlsx
excelcli -q session list
excelcli -q session close --session <id>

GitHub Copilot Plugins (Alternative Installation)

Best for: GitHub Copilot users who want packaged Excel automation plugins through supported plugin surfaces

ExcelMcp ships two GitHub Copilot marketplace plugins:

Copilot CLI Plugin Installation

copilot plugin marketplace add sbroenne/mcp-server-excel-plugins
copilot plugin install excel-mcp@mcp-server-excel-plugins
copilot plugin install excel-cli@mcp-server-excel-plugins

After Installation:

dotnet tool install --global Sbroenne.ExcelMcp.CLI
excelcli --version

Note: The Copilot CLI install commands above are specific to the GitHub Copilot plugin marketplace. VS Code and Claude have their own plugin systems with separate installation flows.

Plugins are published automatically after each ExcelMcp release, though you may need to wait a few moments for the update to appear in the marketplace.

Alternative: NuGet .NET Tool Installation (Secondary)

For users who prefer package managers or already have .NET installed

NuGet is a secondary distribution channel. It requires the .NET 10 Runtime or SDK to be installed.

dotnet tool install --global Sbroenne.ExcelMcp.McpServer
dotnet tool install --global Sbroenne.ExcelMcp.CLI

After installation, configure your MCP client with "command": "mcp-excel" (same as standalone exe).

Update via NuGet:

dotnet tool update --global Sbroenne.ExcelMcp.McpServer
dotnet tool update --global Sbroenne.ExcelMcp.CLI

Uninstall:

dotnet tool uninstall --global Sbroenne.ExcelMcp.McpServer
dotnet tool uninstall --global Sbroenne.ExcelMcp.CLI

Why NuGet is secondary: The standalone exe distributions require no .NET runtime, making them easier to install for most users. NuGet is available as an alternative for users who prefer package managers or already have .NET installed in their workflow.

Agent Skills Installation (Cross-Platform)

Best for: Adding AI guidance to coding agents (Copilot, Cursor, Windsurf, Claude Code, Gemini, Codex, etc.)

Skills are auto-installed by the VS Code extension. Plugins and skills are different things: plugins are packaged surface integrations, while skills are reusable AI guidance. For environments where you want skills directly, use the commands below:

npx skills add sbroenne/mcp-server-excel --skill excel-cli

npx skills add sbroenne/mcp-server-excel --skill excel-mcp

npx skills add sbroenne/mcp-server-excel --skill excel-cli -a cursor
npx skills add sbroenne/mcp-server-excel --skill excel-mcp -a claude-code

npx skills add sbroenne/mcp-server-excel --skill excel-cli --global

Supports 43+ agents including claude-code, github-copilot, cursor, windsurf, gemini-cli, codex, goose, cline, continue, replit, and more.

📚 Agent Skills Guide →

Updating ExcelMcp

Check Current Version

mcp-excel --version

excelcli --version

Update to New Version

Standalone exe (primary):

  1. Go to the latest release
  2. Download the new ZIP(s): ExcelMcp-MCP-Server-{version}-windows.zip and/or ExcelMcp-CLI-{version}-windows.zip
  3. Extract and overwrite the existing files in your installation directory
Expand-Archive "ExcelMcp-MCP-Server-1.x.x-windows.zip" -DestinationPath "C:\Tools\ExcelMcp" -Force
  1. Restart your MCP client (VS Code, Claude Desktop, Cursor, etc.)

NuGet (secondary):

dotnet tool update --global Sbroenne.ExcelMcp.McpServer
dotnet tool update --global Sbroenne.ExcelMcp.CLI

Check What’s New

Before updating, check the release notes:

Troubleshooting

Common Issues

1. “mcp-excel is not recognized as an internal or external command”

Solution: mcp-excel.exe is not on your PATH.

Either:

2. MCP Server Not Responding

Check if the exe exists:

where.exe mcp-excel
Test-Path "C:\Tools\ExcelMcp\mcp-excel.exe"

Verify it runs:

mcp-excel --version

3. “Workbook is locked” or “Cannot open file”

Solution: Close all Excel windows before running ExcelMcp

ExcelMcp requires exclusive access to workbooks (Excel COM limitation).

4. MCP Server Still Running Old Version

Solution: Fully restart your MCP client

Uninstallation

Uninstall MCP Server

Remove-Item "C:\Tools\ExcelMcp\mcp-excel.exe" -Force


dotnet tool uninstall --global Sbroenne.ExcelMcp.McpServer

Uninstall CLI

Remove-Item "C:\Tools\ExcelMcp\excelcli.exe" -Force

dotnet tool uninstall --global Sbroenne.ExcelMcp.CLI

Getting Help

Next Steps

After installation:

  1. Learn the basics: Try simple commands like creating worksheets, setting values
  2. Explore features: See README for complete feature list
  3. Read the guides:
  4. Join the community: Star the repo, report issues, contribute improvements

Agent Skills (Optional)

Agent Skills provide domain-specific guidance to AI coding assistants, helping them use Excel MCP Server more effectively.

Note: Agent Skills are for coding agents (GitHub Copilot, Claude Code, Cursor). Claude Desktop uses MCP Prompts instead (included automatically via the MCP Server).

Two Skills for Different Use Cases

Skill Target Best For
excel-cli CLI Tool Coding agents (Copilot, Cursor, Windsurf) - token-efficient, excelcli --help discoverable
excel-mcp MCP Server Conversational AI (Claude Desktop, VS Code Chat) - rich tool schemas, exploratory workflows

VS Code Extension: Skills are installed automatically to ~/.copilot/skills/.

Other Platforms (Claude Code, Cursor, Windsurf, Gemini, Codex, etc.):

npx skills add sbroenne/mcp-server-excel --skill excel-cli

npx skills add sbroenne/mcp-server-excel --skill excel-mcp

npx skills add sbroenne/mcp-server-excel

npx skills add sbroenne/mcp-server-excel --skill excel-cli   # Coding agents
npx skills add sbroenne/mcp-server-excel --skill excel-mcp   # Conversational AI

npx skills add sbroenne/mcp-server-excel --skill '*'

npx skills add sbroenne/mcp-server-excel --skill excel-cli -a cursor
npx skills add sbroenne/mcp-server-excel --skill excel-mcp -a claude-code

Manual Installation:

  1. Download excel-skills-v{version}.zip from GitHub Releases
  2. The package contains both skills:
    • skills/excel-cli/ - for coding agents (Copilot, Cursor, Windsurf)
    • skills/excel-mcp/ - for conversational AI (Claude Desktop, VS Code Chat)
  3. Extract the skill(s) you need to your AI assistant’s skills directory:
    • Copilot: ~/.copilot/skills/excel-cli/ or ~/.copilot/skills/excel-mcp/
    • Claude Code: .claude/skills/excel-cli/ or .claude/skills/excel-mcp/
    • Cursor: .cursor/skills/excel-cli/ or .cursor/skills/excel-mcp/

See: Agent Skills Documentation

Happy automating! 🚀

This site is open source. Improve this page.