Install Excel CLI (excelcli)¶
Installation instructions for the ExcelMcp CLI (excelcli), for coding agents that run terminal commands. It offers the same features as the MCP Server and usually uses fewer AI tokens. Looking for the MCP Server instead? See the MCP Server Installation Guide.
System Requirements¶
Required¶
- Windows OS (Windows 10 or later)
- Microsoft Excel 2016 or later (Desktop version - Office 365, Professional Plus, or Standalone)
- An interactive Windows desktop with Excel available to the signed-in user; ordinary hosted CI runners do not have desktop Excel
.NET runtime is NOT required for npm or the standalone exe — both use the fully self-contained runtime.
The npm option also requires Node.js 18 or later. Install the current LTS with winget install OpenJS.NodeJS.LTS. Windows x64 and ARM64 are supported; ARM64 Node.js uses a native ARM64 executable.
The standalone release includes separate x64 and ARM64 ZIPs. Choose the download that matches your Windows architecture; the ARM64 archive contains a native ARM64 executable.
Optional (for specific features)¶
- Microsoft Analysis Services OLE DB Provider (MSOLAP) - Required for DAX query execution (
evaluate,execute-dmvactions) - Easiest: Install Power BI Desktop (includes MSOLAP)
- Alternative: Microsoft OLE DB Driver for Analysis Services
Quick Start (Recommended)¶
The current excel-cli GitHub Copilot plugin runs the public npm package through npx -y @sbroenne/excelcli@latest; npm manages package resolution and caching. No separate CLI installation is needed for plugin-driven flows. The VS Code extension does not include the CLI (it only bundles the MCP server); use npx or install the CLI separately for agent workflows outside the plugin. For direct use:
Use npm (below) or download the standalone executable if you prefer not to install Node.js.
npm (Primary)¶
All CLI arguments follow the package name, for example:
npx -y @sbroenne/excelcli@latest -q session open "C:\Data\Test.xlsx"
npx -y @sbroenne/excelcli@latest -q session list
## Replace SESSION_ID with the ID returned by session open:
npx -y @sbroenne/excelcli@latest -q session close --session "SESSION_ID"
These commands do not install bare excelcli on PATH. @latest selects the current npm release at invocation, subject to normal caching. It does not replace an already running background service.
Global npm Installation¶
For repeated use with the bare command, install it on your PATH:
The launcher installs @sbroenne/excelcli-win32-x64 or @sbroenne/excelcli-win32-arm64 as an optional dependency, matching the Node.js process architecture. x64 Node.js on ARM64 Windows still uses x64 emulation. There is no automatic fallback if the matching runtime is missing. Do not use --omit=optional. It forwards arguments, standard input/output, and exit codes to the same excelcli.exe; session management and Excel behavior are unchanged.
Avoid installing multiple distributions of excelcli on the same PATH. Use where.exe excelcli to check which installation your shell will run.
Standalone Executable (Also Primary)¶
- Go to the latest release
- Download
ExcelMcp-CLI-{version}-windows.zipfor x64 Windows orExcelMcp-CLI-{version}-windows-arm64.zipfor ARM64 Windows - Extract to a permanent location (e.g.,
C:\Tools\ExcelMcp\)
For ARM64 Windows, use ExcelMcp-CLI-1.x.x-windows-arm64.zip instead.
Add the Standalone CLI to PATH¶
Skip this section for npx and global npm installations.
$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
Standalone Quick Test¶
excelcli --version
excelcli --help
## Test with an existing workbook
excelcli -q session open "C:\Data\Test.xlsx"
excelcli -q session list
## Replace SESSION_ID with the ID returned by session open:
excelcli -q session close --session "SESSION_ID"
GitHub Copilot Plugin¶
Best for: GitHub Copilot CLI users whose agents work through terminal commands and built-in CLI help
The plugin is listed in Awesome Copilot, the default marketplace in current Copilot clients:
Alternatively, install from our direct marketplace:
## Register our direct marketplace (one-time)
copilot plugin marketplace add sbroenne/mcp-server-excel-plugins
## Install the CLI plugin
copilot plugin install excel-cli@mcp-server-excel-plugins
Choose one marketplace for excel-cli; do not install both copies. Existing direct-marketplace installations do not need to move.
Current plugin launch: Use npx -y @sbroenne/excelcli@latest. The plugin also provides bin\start-cli.ps1, which launches the same npm package while preserving quoted JSON arguments in PowerShell 7.4 or later (pwsh); Windows PowerShell 5.1 is not supported. npm resolves the latest tag and manages caching subject to its cache policy; the plugin has no GitHub-release downloader or separate update checker. No global installation helper, PATH change, or separate .NET runtime is required.
The plugin does not put bare excelcli on PATH. For examples that use that command, substitute the npx command or invoke the plugin's PowerShell wrapper. If you also need excelcli directly on your PATH, use the global npm installation or standalone executable above, or install the secondary NuGet tool when .NET 10 is available:
Note: The Copilot CLI install command above is specific to the GitHub Copilot plugin marketplace. VS Code and Claude have their own plugin systems with separate installation flows.
Plugins are published when their distributed content changes. Their version can lag the ExcelMcp product release; the launcher still uses the latest npm runtime.
Alternative: NuGet .NET Tool Installation (Secondary)¶
For users who already have .NET installed or prefer .NET tools
NuGet is a secondary distribution channel. It requires the .NET 10 Runtime or SDK to be installed.
Update via NuGet:
Uninstall:
Why NuGet is secondary: npm and standalone exe distributions require no separate .NET runtime. NuGet remains available for users who prefer .NET tools.
Updating the CLI¶
Check Current Version¶
For npx use npx -y @sbroenne/excelcli@latest --version instead. This reports the foreground CLI executable's version, not necessarily the version of an already running background service.
Update to New Version¶
Before updating: finish operations, explicitly save and close the intended workbook sessions, then stop the CLI service:
For standalone or global installations, use excelcli -q service stop. Normal shutdown closes workbooks opened by ExcelMcp only when they have no unsaved changes. Unsaved or attached workbooks stay open. Excel copies left by an earlier service are reported, not closed. The next workbook command starts the service using the selected CLI executable.
npm:
## One-off invocation using the latest release:
npx -y @sbroenne/excelcli@latest --version
## Update a global installation:
npm install --global @sbroenne/excelcli@latest
## Uninstall a global installation:
npm uninstall --global @sbroenne/excelcli
Standalone exe (primary):
- Go to the latest release
- Download the new ZIP matching your installation:
ExcelMcp-CLI-{version}-windows.zipfor x64 Windows orExcelMcp-CLI-{version}-windows-arm64.zipfor ARM64 Windows - Extract and overwrite the existing files in your installation directory
NuGet (secondary):
Check What's New¶
Before updating, check the changelog or GitHub Releases.
Troubleshooting¶
npm Runtime Package Missing¶
If the launcher cannot find @sbroenne/excelcli-win32-x64 or @sbroenne/excelcli-win32-arm64, reinstall with optional dependencies enabled:
The npm launcher reports an error on macOS/Linux and unsupported Windows architectures rather than attempting to start Excel.
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¶
VBA commands require "Trust access to the VBA project object model" to be enabled manually in Excel:
- Open Excel
- Go to File → Options → Trust Center
- Click "Trust Center Settings"
- Select "Macro Settings"
- Check "✓ Trust access to the VBA project object model"
- Click OK twice
This is a security setting that must be enabled manually. ExcelMcp does not provide a setup-vba-trust or check-vba-trust command and never modifies Trust Center settings automatically.
Current VBA support is procedural and module-focused: - vba status reports blocked access, password protection, and execution mode without changing settings - vba references lists libraries and flags broken references without repairing them - vba search returns limited literal-text matches with source locations and short excerpts - vba list, vba view, and vba read inspect modules and bounded procedure source - vba import creates a new standard module from inline code or --vba-code-file - vba replace-procedure changes one procedure only if its source has not changed and preserves surrounding comments; vba update still replaces a whole module - vba delete removes components and vba run executes existing procedures
For complete VBA command usage and a macro-enabled workbook example, see Automation & Advanced Features.
"Workbook is locked" or "Cannot open file"¶
Use excelcli session discover and excelcli session attach --workbook-id <ID> to connect to the intended workbook if it is already open. For a new open, Excel handles file access and may open the file read-only. Check excelcli workbook get-info for readOnly before editing, and respond to any prompts in Excel.
Permission Issues¶
## Run PowerShell/CMD as Administrator if you encounter permission errors
## excelcli.exe is a standalone exe - no installation needed
Uninstallation¶
Save and close your intended workbook sessions and stop the service first. Remove Copilot's CLI plugin with copilot plugin uninstall excel-cli@awesome-copilot if installed from Awesome Copilot. Use copilot plugin uninstall excel-cli@mcp-server-excel-plugins instead for a direct-marketplace installation. One-off npx use has no global installation to remove.
## Global npm installation:
npm uninstall --global @sbroenne/excelcli
## Standalone exe:
Remove-Item "C:\Tools\ExcelMcp\excelcli.exe" -Force
## NuGet (if installed via dotnet tool):
dotnet tool uninstall --global Sbroenne.ExcelMcp.CLI
Getting Help¶
- Troubleshooting: Troubleshooting · FAQ
- Documentation: GitHub Repository
- Issues: GitHub Issues
- Contributing: Contributing Guide
Next Steps¶
After installation:
- Learn the basics: Try
npx -y @sbroenne/excelcli@latest --help(orexcelcli --helpfor global/standalone installs) and open a test workbook - Explore features: See the feature overview for capabilities. Use CLI help for current actions and inputs across all 33 feature command categories.
- Read the guides:
- MCP Server Installation Guide - for AI assistants like Claude Desktop and Copilot Chat
- Report formatting - optional presentation guidance
- Join the community: Star the repo, report issues, contribute improvements
Happy automating! 🚀