NuGet Downloads License: MIT

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

📦 Bundled with MCP Server - The CLI (excelcli) is included in the unified Sbroenne.ExcelMcp.McpServer package. Install once, get both tools!

The CLI provides 15 command categories with 214 operations matching the MCP Server. Uses 64% fewer tokens than MCP Server because it wraps all operations in a single tool with skill-based guidance instead of loading 23 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

Installation (.NET Global Tool - Recommended)

## Install unified package (includes both MCP Server and CLI)
dotnet tool install --global Sbroenne.ExcelMcp.McpServer

## Verify installation
excelcli --version

## Get help
excelcli --help

🔁 Session Workflow: Always start with excelcli session open <file> (captures the session id), pass --session <id> to other commands, then excelcli session close <id> --save when finished. The CLI reuses the same Excel instance through that lifecycle.

Check for Updates

## Check if newer version is available
excelcli version --check

## Update if available
dotnet tool update --global Sbroenne.ExcelMcp.McpServer

Uninstall

dotnet tool uninstall --global Sbroenne.ExcelMcp.McpServer

🤫 Quiet Mode (Agent-Friendly)

For scripting and coding agents, use -q/--quiet to suppress banner and output JSON only:

excelcli -q session open data.xlsx
excelcli -q range get-values --session 1 --sheet Sheet1 --range A1:B2
excelcli -q session close --session 1 --save

Banner auto-suppresses when stdout is piped or redirected.

🆘 Built-in Help

Descriptions are kept in sync with the CLI source so the help output always reflects the latest capabilities.

✨ Key Features

🔧 Excel Development Automation

📊 Data Operations

🛡️ Production Ready

📋 Command Categories

ExcelMcp.CLI provides 214 operations across 15 command categories:

📚 Complete Feature Reference → - Full documentation with all operations

Quick Reference:

Category Operations Examples
File & Session 6 session create, session open, session close, session list
Worksheets 16 sheet list, sheet create, sheet rename, sheet copy, sheet move, sheet copy-to-file
Power Query 10 powerquery list, powerquery create, powerquery refresh, powerquery update
Ranges 42 range get-values, range set-values, range copy, range find, range merge-cells
Conditional Formatting 2 conditionalformat add-rule, conditionalformat clear-rules
Excel Tables 27 table create, table apply-filter, table get-data, table sort, table add-column
Charts 14 chart create-from-range, chart list, chart delete, chart move, chart fit-to-range
Chart Config 14 chartconfig set-title, chartconfig add-series, chartconfig set-style, chartconfig data-labels
PivotTables 30 pivottable create-from-range, pivottable add-row-field, pivottable refresh
Slicers 8 slicer create-slicer, slicer list-slicers, slicer set-slicer-selection
Data Model 19 datamodel create-measure, datamodel create-relationship, datamodel evaluate
Connections 9 connection list, connection refresh, connection test
Named Ranges 6 namedrange create, namedrange read, namedrange write, namedrange update
VBA 6 vba list, vba import, vba run, vba update
Calculation Mode 3 calculation get-mode, calculation set-mode, calculation calculate

Note: CLI uses session commands for multi-operation workflows.

SESSION LIFECYCLE (Open/Save/Close)

The CLI uses an explicit session-based workflow where you open a file, perform operations, and optionally save before closing:

## 1. Open a session
excelcli session open data.xlsx
## Output: Session ID: 550e8400-e29b-41d4-a716-446655440000

## 2. List active sessions anytime
excelcli session list

## 3. Use the session ID with any commands
excelcli sheet create --session 550e8400-e29b-41d4-a716-446655440000 --sheet "NewSheet"
excelcli powerquery list --session 550e8400-e29b-41d4-a716-446655440000

## 4. Close and save changes
excelcli session close 550e8400-e29b-41d4-a716-446655440000 --save

## OR: Close and discard changes (no --save flag)
excelcli session close 550e8400-e29b-41d4-a716-446655440000

Session Lifecycle Benefits

Background Service & System Tray

When you run your first CLI command, the ExcelMCP Service starts automatically in the background. The service:

Tray Icon Features:

The service auto-stops after 10 minutes of inactivity (no active sessions).

💡 Command Reference

Use excelcli <command> --help for complete parameter documentation. The CLI help is always in sync with the code.

excelcli --help              # List all commands
excelcli session --help      # Session lifecycle (open, close, save, list)
excelcli powerquery --help   # Power Query operations
excelcli range --help        # Cell/range operations
excelcli table --help        # Excel Table operations
excelcli pivottable --help   # PivotTable operations
excelcli datamodel --help    # Data Model & DAX
excelcli vba --help          # VBA module management

Typical Workflows

Session-based automation (recommended):

excelcli -q session open report.xlsx           # Returns session ID
excelcli -q sheet create --session 1 --sheet "Summary"
excelcli -q range set-values --session 1 --sheet Summary --range A1 --values '[["Hello"]]'
excelcli -q session close --session 1 --save   # Persist changes

Power Query ETL:

excelcli powerquery create --session 1 --query "CleanData" --mcode-file transform.pq
excelcli powerquery refresh --session 1 --query "CleanData"

PivotTable from Data Model:

excelcli pivottable create-from-datamodel --session 1 --table Sales --dest-sheet Analysis --dest-cell A1 --pivot-table SalesPivot
excelcli pivottable add-row-field --session 1 --pivot-table SalesPivot --field Region
excelcli pivottable add-value-field --session 1 --pivot-table SalesPivot --field Amount --function Sum

VBA automation:

excelcli vba import --session 1 --module "Helpers" --code-file helpers.vba
excelcli vba run --session 1 --macro "Helpers.ProcessData"

⚙️ System Requirements

Requirement Details Why Required
Windows OS Windows 10/11 or Server 2016+ COM interop is Windows-specific
Microsoft Excel Excel 2016 or later CLI controls actual Excel application
.NET 10 Runtime Download Required to run .NET global tools

Note: ExcelMcp.CLI controls the actual Excel application via COM interop, not just file formats. This provides access to Power Query, VBA runtime, formula engine, and all Excel features, but requires Excel to be installed.

🔒 VBA Operations Setup (One-Time)

VBA commands require “Trust access to the VBA project object model” to be enabled:

  1. Open Excel
  2. Go to File → Options → Trust Center
  3. Click “Trust Center Settings”
  4. Select “Macro Settings”
  5. Check “✓ Trust access to the VBA project object model”
  6. Click OK twice

This is a security setting that must be manually enabled. ExcelMcp.CLI never modifies security settings automatically.

For macro-enabled workbooks, use .xlsm extension:

excelcli session create macros.xlsm
## Returns session ID (e.g., 1)
excelcli vba import --session 1 --module MyModule --code-file code.vba
excelcli session close --session 1 --save

📖 Complete Documentation

🚧 Troubleshooting

Command Not Found After Installation

## Verify .NET tools path is in your PATH environment variable
dotnet tool list --global

## If excelcli is listed but not found, add .NET tools to PATH:
## The default location is: %USERPROFILE%\.dotnet\tools

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: Enable VBA trust (see VBA Operations Setup above)

Permission Issues

## Run PowerShell/CMD as Administrator if you encounter permission errors
## Or install to user directory: dotnet tool install --global Sbroenne.ExcelMcp.CLI

🛠️ 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: Install ExcelMcp.CLI
  run: dotnet tool install --global Sbroenne.ExcelMcp.CLI

- name: Process Excel Files
  run: |
    SESSION=$(excelcli session open data.xlsx | grep "Session ID:" | cut -d' ' -f3)
    excelcli powerquery create --session $SESSION --query "Query1" --mcode-file queries/query1.pq
    excelcli powerquery refresh --session $SESSION --query "Query1"
    excelcli session close $SESSION --save

✅ 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.

🤝 Related Tools

📄 License

MIT License - see LICENSE for details.

🙋 Support

Built with ❤️ for Excel developers and automation engineers

This site is open source. Improve this page.