Skip to content

CLI Documentation

GitHub Release GitHub Downloads NuGet License: MIT

Command-line interface for Excel automation — preferred by coding agents.

Primary distribution: Standalone executable — Download excelcli.exe from the latest release. No .NET runtime required. Secondary distribution: NuGet .NET tool — dotnet tool install --global Sbroenne.ExcelMcp.CLI (requires .NET 10 runtime).

The CLI provides 18 command categories with 234 operations matching the MCP Server — the same capabilities, just packaged as 18 CLI command categories instead of the MCP Server's 26 tools. It uses 64% fewer tokens than the MCP Server because it wraps all operations in a single tool with skill-based guidance instead of loading 26 tool schemas into context.

Interface Best For Why
CLI (excelcli) Coding agents (Copilot, Cursor, Windsurf) 64% fewer tokens - single tool, no large schemas
MCP Server Conversational AI (Claude Desktop, VS Code Chat) Rich tool discovery, persistent connection

Also perfect for RPA workflows, CI/CD pipelines, batch processing, and automated testing.

➡️ Learn more and see examples

🚀 Quick Start

Primary Installation: Standalone Executable

  1. Download ExcelMcp-CLI-{version}-windows.zip from the latest release
  2. Extract excelcli.exe to a permanent location (e.g., C:\Tools\ExcelMcp\) and add the directory to your PATH
  3. Verify: excelcli --version and excelcli --help

Secondary Installation: .NET Global Tool

## Requires .NET 10 Runtime or SDK
dotnet tool install --global Sbroenne.ExcelMcp.CLI

📖 Full Installation Guide - PATH setup, GitHub Copilot plugin, updating, uninstalling, and troubleshooting

📚 Complete CLI Usage Guide - Session workflow, quiet mode, command reference, typical workflows, CI/CD examples

🔁 Session Workflow: Always start with excelcli session open <file> (captures the session id), pass --session <id> to other commands, then excelcli session close --session <id> --save when finished. Add --show when Excel must stay visible for IRM/AIP sign-in or other authentication prompts.

📋 What You Can Do

ExcelMcp.CLI provides 234 operations across 18 command categories: Power Query, Data Model/DAX, PivotTables, Excel Tables, Charts, VBA, Ranges, Worksheets, Connections, Named Ranges, Conditional Formatting, Slicers, Calculation Mode, Python in Excel, Screenshot, File & Session, and Window Management.

Drives the actual Excel application via COM — not a file-format parser — so live operations (Power Query refresh, recalculation, DAX evaluation, VBA execution) run for real and existing workbooks stay intact.

📚 Complete Feature Reference → - Full documentation with all operations, grouped by category

⚙️ System Requirements

  • Windows OS (Windows 10/11 or Server 2016+) + Microsoft Excel 2016 or later — COM interop is Windows-specific and requires Excel to be installed
  • .NET 10 Runtime only if using the NuGet .NET tool install path (not required for the standalone exe)

📖 Full System Requirements & Optional Components - including DAX/MSOLAP prerequisites

📖 Complete Documentation

🚧 Troubleshooting

Command Not Found After Installation

## Check excelcli.exe location
where.exe excelcli

## If not found, ensure the directory containing excelcli.exe is in your PATH
## The default location after extraction might be: C:\Tools\ExcelMcp\

Excel Not Found

## Error: "Microsoft Excel is not installed"
## Solution: Install Microsoft Excel (any version 2016+)

VBA Access Denied

## Error: "Programmatic access to Visual Basic Project is not trusted"
## Solution: In Excel, enable File → Options → Trust Center → Trust Center Settings
##           → Macro Settings → "Trust access to the VBA project object model"

Permission Issues

## Run PowerShell/CMD as Administrator if you encounter permission errors
## excelcli.exe is a standalone exe - no installation needed

IRM / AIP Protected Workbooks

## Keep Excel visible so authentication or policy prompts can surface
excelcli session open "D:\Docs\Protected.xlsx" --show --timeout 120

Use --show whenever hidden automation would block on a sign-in, consent, or information-protection prompt.

🛠️ Advanced Usage

Scripting & Automation

## PowerShell script example
$files = Get-ChildItem *.xlsx
foreach ($file in $files) {
    $session = excelcli session open $file.Name | Select-String "Session ID: (.+)" | ForEach-Object { $_.Matches.Groups[1].Value }
    excelcli powerquery refresh --session $session --query "Sales Data"
    excelcli datamodel refresh --session $session
    excelcli session close $session --save
}

CI/CD Integration

## GitHub Actions example
- name: Download ExcelMcp CLI
  run: |
    $version = (Invoke-RestMethod "https://api.github.com/repos/sbroenne/mcp-server-excel/releases/latest").tag_name.TrimStart('v')
    Invoke-WebRequest "https://github.com/sbroenne/mcp-server-excel/releases/download/v$version/ExcelMcp-CLI-$version-windows.zip" -OutFile cli.zip
    Expand-Archive cli.zip -DestinationPath C:\Tools\ExcelMcp
    echo "C:\Tools\ExcelMcp" >> $env:GITHUB_PATH
  shell: pwsh

- name: Process Excel Files
  run: |
    $session = (excelcli session open data.xlsx | Select-String "Session ID:").ToString().Split()[-1]
    excelcli powerquery create --session $session --query-name "Query1" --m-code-file queries/query1.pq
    excelcli powerquery refresh --session $session --query-name "Query1"
    excelcli session close --session $session --save
  shell: pwsh

✅ Tested Scenarios

The CLI ships with real Excel-backed integration tests that exercise the session lifecycle plus worksheet creation/listing flows through the same commands you run locally. Execute them with:

dotnet test tests/ExcelMcp.CLI.Tests/ExcelMcp.CLI.Tests.csproj --filter "Layer=CLI"

These tests open actual workbooks, issue session open/list/close, and call excelcli sheet actions to ensure the command pipeline stays healthy.

📄 License

MIT License - see LICENSE for details.

Built with ❤️ for Excel developers and automation engineers