mcp-excel

A Model Context Protocol server that gives Claude Code (or any MCP client) full read and write access to Excel workbooks: sheets, cell ranges, structured tables, formulas, formatting, and cross-workbook references. It reads and writes real .xlsx files on disk using ExcelJS; no copy of Excel, no Microsoft account, and no cloud service are required.

It runs locally as a stdio subprocess, or as an HTTP/SSE service (handy for sharing one instance with a desktop client over your LAN via Docker).

Status: 11 tools, stdio + SSE transports, zero external dependencies beyond npm. License: MIT.

Tools

Tool	What it does
list_sheets	List all sheets in a workbook with row/column counts
read_range	Read a range of cells; returns values, formulas, and types
write_cells	Write values or formulas to specific cells (creates the file/sheet if missing)
write_rows	Write multiple rows of data from a starting cell (bulk dataset building)
create_table	Create a structured Excel Table (ListObject) with headers, data, and optional column formulas
create_workbook	Create a new empty workbook with one or more named sheets
add_sheet	Add a new sheet to an existing workbook
delete_sheet	Delete a sheet from a workbook
format_cells	Apply font, fill, number format, alignment, and borders to a range
cross_workbook_reference	Read from one workbook and write values (or linking formulas) into another
get_defined_names	List named ranges and table names in a workbook

All file-path arguments are resolved with path.resolve() against the server's working directory, so absolute paths are the safest. In Docker (SSE) mode, paths resolve inside the container against the mounted /data volume (see below).

Requirements

• Node.js 18 or newer (stdio mode), or
• Docker (SSE / shared-instance mode)

Setup: Claude Code (stdio, local)

Clone and install:

git clone https://github.com/Corvalon/mcp-excel.git
cd mcp-excel
npm ci

Register the server. Either add it with the CLI:

claude mcp add excel -- node /absolute/path/to/mcp-excel/index.js

or add it by hand to your Claude Code config (~/.claude.json):

{
  "mcpServers": {
    "excel": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-excel/index.js"]
    }
  }
}

Restart Claude Code. The tools appear under the mcp__excel__* prefix.

Setup: Claude Desktop (stdio, local)

Add the same block to Claude Desktop's config (Settings > Developer > Edit Config, which opens claude_desktop_config.json):

{
  "mcpServers": {
    "excel": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-excel/index.js"]
    }
  }
}

Save and restart. When the hammer / tools icon appears, the server is connected.

Setup: Docker (SSE, shared instance)

Run one container that any MCP client on your network can reach over SSE. This is useful for driving Excel files from a machine that does not have Node.js.

1. Point the container at the folder that holds your workbooks and start it:

   MCP_EXCEL_DATA_DIR=/path/to/your/spreadsheets docker compose up -d --build
   

   The compose file mounts that folder as /data inside the container and listens on port 3001.

2. Add the SSE endpoint to your client config (replace the host with the container host's LAN IP if the client is on another machine):

   {
     "mcpServers": {
       "excel": {
         "url": "http://localhost:3001/sse"
       }
     }
   }
   

3. Because paths resolve inside the container, address files relative to the /data mount. If MCP_EXCEL_DATA_DIR is ~/spreadsheets, then ~/spreadsheets/2025/Budget.xlsx is /data/2025/Budget.xlsx in tool calls.

When a client on a different host connects over SSE, set MCP_ALLOWED_HOSTS so the server accepts the request. Create a .env file next to docker-compose.yml:

MCP_ALLOWED_HOSTS='localhost,127.0.0.1,::1,192.168.1.50,my-host.local'

Container management:

docker compose up -d --build   # start / rebuild after code changes
docker compose down            # stop
docker compose logs -f         # tail logs

A health check is available at http://<host>:3001/health.

Configuration

Variable	Default	Purpose
MCP_TRANSPORT	stdio	stdio for a local subprocess, sse for the HTTP/SSE service
MCP_PORT	3000	Port for SSE mode (the Docker compose file uses 3001)
MCP_ALLOWED_HOSTS	localhost,127.0.0.1,::1	Comma-separated Host-header allowlist for SSE mode
MCP_EXCEL_DATA_DIR	./data	Host folder mounted as /data in the Docker container

Security

This server reads and writes real files, and in SSE mode it opens a network port. Treat it as trusted-local tooling, not an internet-facing service.

• File access. Tool calls can read or write any .xlsx path the server process can reach. In stdio mode that is your whole filesystem; in Docker (SSE) mode it is scoped to the mounted /data volume, so Docker is the safer way to bound access.
• SSE has no authentication. The HTTP/SSE endpoint listens on 0.0.0.0 and does not authenticate callers. Only run it on a trusted LAN, and restrict who can reach it with MCP_ALLOWED_HOSTS (a Host-header allowlist) plus your own firewall. Do not expose port 3001 to the public internet.
• Formulas are data, not code. ExcelJS writes formula strings; it does not execute macros or VBA, so opening a produced workbook runs no code from this server.

Example prompts

• "Create a new budget workbook with columns Category, Budget, Actual, and Difference."
• "Read the data in Sales.xlsx and summarize the totals by region."
• "Add a SUM formula at the bottom of column B in the Q1 sheet."
• "Build a formatted table from this data with a totals row."
• "Pull the monthly totals from Budget.xlsx into a Summary sheet in Report.xlsx."

Notes and gotchas

Operator/agent notes (permission wildcards, exact-parameter-name behavior, the openpyxl fallback, and formula-result caching) live in CLAUDE.md.

License

MIT (c) 2026 Corvalon.