Excel MCP

Excel MCP is a Python MCP server and companion CLI for safe, token-efficient work with local Excel .xlsx workbooks.

It is designed for financial and operations workflows such as bookkeeping, accounting, marketing operations, SEO exports, research tables, reconciliations, and financial report review.

Core behavior:

• Describe workbook structure before reading bulk data.
• Query detected worksheet regions with DuckDB SQL.
• Inspect exact ranges only when needed.
• Stage writes as dry-runs.
• Diff before commit.
• Save edits to a new workbook by default.
• Keep an audit trail of reads, queries, staged writes, diffs, commits, and failures.

Google Sheets and Apple Numbers are not supported in this phase.

Install

Recommended: uvx

If uv is installed, run the MCP server without creating a virtual environment:

uvx excel-ops-mcp

Run the CLI without a persistent install:

uvx --from excel-ops-mcp excel-ops sheets workbook.xlsx

One-command install (all agents)

Bootstraps uv if needed, then opens a picker to install excel-ops-mcp into Claude Desktop, Claude Code, Codex, Gemini CLI, Cursor, and/or Windsurf:

curl -LsSf https://raw.githubusercontent.com/dasein108/excel-ops-mcp/main/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/dasein108/excel-ops-mcp/main/install.ps1 | iex"

The picker first asks Install or Uninstall, then shows a [ ]/[X] checkbox list (everything unchecked to start). Toggle agents by number and press Enter. Each agent is labelled installed / detected / not found.

Non-interactive: ... | sh -s -- --agents cursor,claude-code to install, or --uninstall cursor,claude-code to remove. Preview with --dry-run; see status with --list.

Install uv

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Homebrew:

brew install uv

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

After installation, restart your shell if uvx is not found.

Persistent CLI Install

Use pipx if you want excel-ops-mcp and excel-ops installed persistently:

pipx install excel-ops-mcp
excel-ops sheets workbook.xlsx

Developer Install

git clone <repo-url>
cd excel_mcp
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev,install]"
pytest -v

MCP Configuration

The fastest way to configure any supported host (Claude Desktop, Claude Code, Codex, Gemini CLI, Cursor, Windsurf) is the one-command installer, which writes the correct config for each agent automatically.

To configure a host manually, for MCP hosts that support command-based servers:

{
  "mcpServers": {
    "excel-mcp": {
      "command": "uvx",
      "args": ["excel-ops-mcp"]
    }
  }
}

For local development:

{
  "mcpServers": {
    "excel-mcp": {
      "command": "/absolute/path/to/excel_mcp/.venv/bin/excel-ops-mcp"
    }
  }
}

Allowed roots (which files the server may touch)

For safety the server only reads and writes .xlsx files under its allowed roots. When launched by a desktop host the working directory is unhelpful (often /), so the server defaults its allowed root to your home directory — enough to open and save workbooks anywhere under ~.

To restrict or extend that, set EXCEL_MCP_ALLOWED_ROOTS (os.pathsep-separated: : on macOS/Linux, ; on Windows) in the server's env:

{
  "mcpServers": {
    "excel-mcp": {
      "command": "uvx",
      "args": ["excel-ops-mcp"],
      "env": { "EXCEL_MCP_ALLOWED_ROOTS": "/Users/you/Documents:/Users/you/work" }
    }
  }
}

Equivalently, pass --allowed-root <dir> (repeatable) in args. Writes still go to a new file by default and never overwrite the source unless you ask.

macOS note: if the host app is sandboxed, macOS may additionally block the server from reading ~/Desktop, ~/Documents, or ~/Downloads until you grant the app Files-and-Folders (or Full Disk) access in System Settings → Privacy & Security. An empty read with a permission error there is an OS gate, not an allowed-root problem.

MCP Tools

spreadsheet_open

Open a local .xlsx workbook and return a session ID.

Input:

{
  "path": "/path/to/workbook.xlsx"
}

Output includes:

• session_id
• resolved path
• file size
• mtime
• cache telemetry

spreadsheet_describe

Describe workbook sheets, detected regions, SQL table names, columns, formulas, merged ranges, and source references.

Input:

{
  "session_id": "ses_...",
  "detail": "compact"
}

Use detail: "standard" only when sample rows are needed. Compact mode avoids long cell text by default.

spreadsheet_query

Run read-only DuckDB SQL over detected workbook regions.

Input:

{
  "session_id": "ses_...",
  "sql": "select line_item, jan from \"revenue_model_table_1\" limit 5",
  "limit": 1000
}

Mutation statements are rejected. Writes must go through structured write operations.

Percent-like columns may expose derived numeric columns:

• <column>__kind
• <column>__num
• <column>__min
• <column>__max

Use __max for mixed APY/range values such as 0.34, 10-30%, and от 11% до 80%+.

spreadsheet_read_range

Read a bounded cell range for exact inspection.

Input:

{
  "session_id": "ses_...",
  "sheet": "Sheet1",
  "range": "A1:F20",
  "include": ["values", "formulas"]
}

Supported include values:

• values — computed value. Formula cells return the number Excel cached in the file, not the formula text.
• formulas — the formula string (e.g. =B11+B16+B20).
• number_formats
• comments
• hyperlinks
• styles
• merged

spreadsheet_query likewise materializes computed values, so SQL can aggregate formula columns. When a formula has no cached value (files never opened in a spreadsheet app), the cell returns null with a computed_value_unavailable warning; install the recompute extra to evaluate it:

pip install 'excel-ops-mcp[recompute]'

spreadsheet_trace

Trace a cell's formula lineage — its precedents, cross-sheet aware, with computed values, recursing up to depth (0–5).

Input:

{ "session_id": "ses_...", "sheet": "Dashboard", "cell": "B5", "depth": 2 }

Returns target with formula, value, and a nested precedents tree. Use it to answer "where does this number come from?" and "how is X computed?" instead of hand-parsing formulas.

spreadsheet_write

Stage structured write operations. This is a dry-run preview and does not mutate the source file.

Input:

{
  "session_id": "ses_...",
  "dry_run": true,
  "operations": [
    {
      "type": "set_values",
      "sheet": "Ops",
      "start": "E2",
      "values": [["reviewed"]]
    }
  ]
}

Supported operations:

• set_values
• set_formula
• clear_range
• append_rows
• insert_rows
• delete_rows
• copy_range

spreadsheet_diff

Return the staged diff before commit.

Input:

{
  "session_id": "ses_...",
  "staged_id": "stg_..."
}

spreadsheet_commit

Commit staged changes to a workbook file. Saves to a new output path by default.

Input:

{
  "session_id": "ses_...",
  "staged_id": "stg_...",
  "output_path": "/path/to/workbook.updated.xlsx",
  "overwrite": false
}

Source overwrite is rejected unless overwrite is explicitly true.

CLI

The excel-ops CLI exposes the same engine without starting an MCP server.

Command Reference

Every base command, and the MCP tool it mirrors:

Shared flags: --pretty (readable JSON), --allowed-root <dir> (permit paths outside the current directory), --cache-dir <dir> (persist session and staged ids across chained commands).

Discover Sheets

excel-ops sheets examples/Financial_Report.xlsx --pretty

Discover Tables

excel-ops tables examples/saas.xlsx --pretty

Filter to a sheet:

excel-ops tables examples/saas.xlsx --sheet "Revenue Model" --pretty

Query

excel-ops query examples/saas.xlsx \
  --sql 'select line_item, jan from "revenue_model_table_1" limit 5' \
  --pretty

Read A Range

excel-ops read-range examples/saas.xlsx \
  --sheet "Revenue Model" \
  --range A1:D5 \
  --include values \
  --pretty

Safe Write Workflow

Open a workbook and keep the same cache directory across commands:

excel-ops open workbook.xlsx --cache-dir /tmp/excel-ops-cache --pretty

Create operations:

[
  {
    "type": "set_values",
    "sheet": "Ops",
    "start": "E2",
    "values": [["reviewed"]]
  }
]

Stage the write:

excel-ops write --session ses_... --ops ops.json --cache-dir /tmp/excel-ops-cache --pretty

Review the diff:

excel-ops diff --session ses_... --staged stg_... --cache-dir /tmp/excel-ops-cache --pretty

Commit to a new workbook:

excel-ops commit \
  --session ses_... \
  --staged stg_... \
  --output workbook.updated.xlsx \
  --cache-dir /tmp/excel-ops-cache \
  --pretty

Audit Trail

excel-ops audit --session ses_... --cache-dir /tmp/excel-ops-cache --pretty

Use as an Agent Skill

The Excel workflow ships as a single, harness-agnostic skill so the same guidance works from Claude Code, Codex, or any MCP host. There is one source of truth and thin per-harness pointers.

Canonical skill (edit here):

agents/skills/excel-ops/SKILL.md
agents/skills/excel-ops/references/cli-workflows.md

Per-harness pointers (load the skill in each tool, frontmatter only):

• Claude Code / Claude plugins: .claude/skills/excel-ops/SKILL.md
• Codex: .codex/skills/excel-ops/SKILL.md (plus Codex host config agents/openai.yaml)

All three delivery channels drive the same engine:

• MCP host — the spreadsheet_* tools above.
• CLI — the excel-ops commands above.
• Agent skill — tells the agent to prefer the excel-ops CLI over ad hoc scripts and to follow the stage → diff → commit safety contract.

The skill teaches this order: sheets → tables → query → read-range (exact inspection only) → write → diff → commit → audit.

The CLI is the deterministic interface. The skill is only guidance; it never implements spreadsheet logic itself.

Safety Model

• Only local .xlsx files are supported.
• Paths are restricted to configured allowed roots.
• SQL is read-only.
• Writes are structured JSON operations.
• Writes are staged before commit.
• Commit saves to a new file unless overwrite is explicit.
• Audit events are stored in the configured cache directory.

Background & Research

This project's design — DuckDB SQL over detected regions, workbook sessions, and a stage → diff → commit write contract — draws on a survey of the Excel/spreadsheet MCP landscape and a DuckDB-aware architecture comparison. See docs/RESEARCH_AND_COMPETITORS.md.

Development

See docs/DEVELOPMENT.md for local development, tests, package builds, and PyPI release automation.