---
name: excel-cli
description: >
Automate Microsoft Excel on Windows via CLI. Use when creating, reading,
or modifying Excel workbooks from scripts, CI/CD, or coding agents.
Supports Power Query, DAX, PivotTables, Tables, Ranges, Charts, VBA.
Triggers: Excel, spreadsheet, workbook, xlsx, excelcli, CLI automation.
compatibility: Windows + Microsoft Excel 2016+ required. Uses COM interop - does NOT work on macOS or Linux.
allowed-tools: Cmd(excelcli:*),PowerShell(excelcli:*)
disable-model-invocation: true
license: MIT
version: 1.4.0
repository: https://github.com/sbroenne/mcp-server-excel
documentation: https://excelmcpserver.dev/
---
# Excel Automation with excelcli
## CRITICAL RULES (MUST FOLLOW)
### Rule 1: NEVER Ask Clarifying Questions
Execute commands to discover the answer instead:
| DON'T ASK | DO THIS INSTEAD |
|-----------|-----------------|
| "Which file should I use?" | `excelcli -q session list` |
| "What table should I use?" | `excelcli -q table list --session <id>` |
| "Which sheet has the data?" | `excelcli -q sheet list --session <id>` |
**You have commands to answer your own questions. USE THEM.**
### Rule 2: Use File-Based Input for Complex Data
PowerShell cannot reliably parse inline JSON or M code:
```powershell
# CORRECT - Use --values-file
$data = '[["Name","Price"],["Widget",100]]'
$data | Out-File -Encoding UTF8 C:\temp\data.json
excelcli -q range set-values --session 1 --sheet Sheet1 --range A1 --values-file C:\temp\data.json
# CORRECT - Use --mcode-file for Power Query
$mcode | Out-File -Encoding UTF8 C:\temp\query.m
excelcli -q powerquery create --session 1 --query Products --mcode-file C:\temp\query.m
```
### Rule 3: Session Lifecycle
```powershell
excelcli -q session open C:\path\file.xlsx # Returns session ID
excelcli -q range set-values --session 1 ... # Use session ID
excelcli -q session close --session 1 --save # Save and release
```
**Unclosed sessions leave Excel processes running, locking files.**
### Rule 4: Data Model Prerequisites
DAX operations require tables in the Data Model:
```powershell
excelcli -q table add-to-datamodel --session 1 --table Sales # Step 1
excelcli -q datamodel create-measure --session 1 ... # Step 2 - NOW works
```
### Rule 5: Power Query Development Lifecycle
**BEST PRACTICE: Test M code before creating permanent queries**
```powershell
# Step 1: Test M code without persisting (catches errors early)
excelcli -q powerquery evaluate --session 1 --mcode-file query.m
# Step 2: Create permanent query with validated code
excelcli -q powerquery create --session 1 --query Q1 --mcode-file query.m
# Step 3: Load data to destination
excelcli -q powerquery refresh --session 1 --query Q1
```
**Why evaluate first:** Better error messages than COM exceptions, see actual data preview, avoids broken queries in workbook.
### Rule 6: Report File Errors Immediately
If you see "File not found" or "Path not found" - STOP and report to user. Don't retry.
### Rule 7: Use Calculation Mode for Bulk Writes
When writing many values/formulas (10+ cells), disable auto-recalc for performance:
```powershell
# 1. Set manual mode
excelcli -q calculationmode set-mode --session 1 --mode manual
# 2. Perform bulk writes
excelcli -q range set-values --session 1 --sheet Sheet1 --range A1 --values-file data.json
# 3. Recalculate once at end
excelcli -q calculationmode calculate --session 1 --scope workbook
# 4. Restore automatic mode
excelcli -q calculationmode set-mode --session 1 --mode automatic
```
**When NOT needed:** Reading formulas, small edits (1-10 cells), or when you need immediate calculation results.
## Quick Reference
| Task | Command |
|------|---------|
| Open workbook | `excelcli -q session open <path>` |
| List sheets | `excelcli -q sheet list --session <id>` |
| Read data | `excelcli -q range get-values --session <id> --sheet Sheet1 --range A1:D10` |
| Create table | `excelcli -q table create --session <id> --sheet Sheet1 --range A1:D10 --name Sales` |
| Add to Data Model | `excelcli -q table add-to-datamodel --session <id> --table Sales` |
| Create pivot | `excelcli -q pivottable create --session <id> --source Sales --dest-sheet Analysis` |
| Save & close | `excelcli -q session close --session <id> --save` |
**Primary source:** `excelcli <command> --help` for authoritative parameter info.
## Reference Documentation
- @references/behavioral-rules.md - Core execution rules and LLM guidelines
- @references/anti-patterns.md - Common mistakes to avoid
- @references/workflows.md - Data Model constraints and patterns
## Installation
```powershell
dotnet tool install --global Sbroenne.ExcelMcp.CLI
```
