excel-mcp-server

A Model Context Protocol server that lets AI assistants create, read and edit Excel workbooks. It needs no Microsoft Excel installation.

• Read and write cells, formulas (with results calculated for you) and dates, with paging and streaming reads for large sheets, and search
• Format fonts, fills, borders, number formats, column widths and frozen panes; hide or group rows, columns and sheets; set up printing; protect sheets
• Structure sheets (order, view, workbook settings and protection), rows and columns (inserting or deleting updates every reference, as in Excel), merged cells, tables (totals row, calculated columns, banding, filter buttons, resizing), charts (column, bar, line, area, pie, doughnut, radar, scatter and bubble, with combos, secondary axes, trendlines and error bars; and the Excel 2016 waterfall, histogram, Pareto, box and whisker, treemap, sunburst and funnel), images, hyperlinks, PivotTables, and slicers and timelines that filter them and tables
• Data tools: paste special, fill series, remove duplicates, text to columns, find and replace, sheet and table filters with criteria
• Rules: conditional formatting (scales, data bars with borders, negative bars and axis, icon sets with custom icons, top/bottom, duplicates, text, dates and more), sparklines (line, column, win/loss) and data validation (dropdowns from cells, limits, input messages, alert styles), cleared with clear_range
• Macros: read the VBA code in .xlsm files, module by module (never run). Writing VBA is off unless you start the server with --allow-vba-write (see below)
• Safe by design: optional folder confinement, a formula safety check, read-only mode, localhost-only HTTP by default, and atomic saves that never leave a half-written file

Works with .xlsx, .xlsm (macros are preserved), .xltx and .xltm files.

Quick start

You need uv. Every client runs the server with uvx excel-mcp-server stdio; replace /path/to/workbooks with the folder the server may use.

Claude Desktop (Chat): download excel-mcp-server-<version>.mcpb from the latest release and open it. Claude asks which folder the server may use.

Claude Code (the CLI, and the Code tab in Claude Desktop):

claude mcp add excel --scope user -- uvx excel-mcp-server stdio --allow-dir /path/to/workbooks

Cursor (~/.cursor/mcp.json), and most clients that use an mcpServers config:

{
  "mcpServers": {
    "excel": {
      "command": "uvx",
      "args": ["excel-mcp-server", "stdio", "--allow-dir", "/path/to/workbooks"]
    }
  }
}

VS Code with GitHub Copilot (.vscode/mcp.json, note the servers key):

{
  "servers": {
    "excel": {
      "type": "stdio",
      "command": "uvx",
      "args": ["excel-mcp-server", "stdio", "--allow-dir", "${workspaceFolder}"]
    }
  }
}

OpenAI Codex (CLI, IDE extension and app):

codex mcp add excel -- uvx excel-mcp-server stdio --allow-dir /path/to/workbooks

Gemini CLI:

gemini mcp add -s user excel uvx excel-mcp-server stdio --allow-dir /path/to/workbooks

Devin Desktop:

devin mcp add -s user excel -- uvx excel-mcp-server stdio --allow-dir /path/to/workbooks

Claude Desktop, manual setup: open Settings, Developer, Edit Config, add the mcpServers JSON above to claude_desktop_config.json, and restart Claude.

Desktop apps often cannot find uvx, because they do not see your shell's PATH (common on macOS). Use its full path instead, which which uvx prints.

Choosing which files it can use

With --allow-dir DIR, the server only opens workbooks inside DIR (subfolders included) and relative paths such as reports/q1.xlsx start there. Repeat the flag to allow several folders, or set EXCEL_FILES_PATH (separate folders with : on macOS/Linux and ; on Windows).

Without --allow-dir, any absolute path to an Excel file works. In every mode the server only touches Excel files and never silently overwrites an existing workbook.

Remote use (Streamable HTTP)

uvx excel-mcp-server streamable-http --allow-dir /srv/workbooks

Clients connect to http://127.0.0.1:8017/mcp. Workbooks live in the --allow-dir folder (default ./excel_files), and export_workbook / import_workbook move files between the server and the client.

The server listens on localhost only. To accept other machines, set a token and a host:

EXCEL_MCP_AUTH_TOKEN=change-me uvx excel-mcp-server streamable-http --host 0.0.0.0

Clients then send Authorization: Bearer change-me. Put a TLS-terminating reverse proxy in front of it for use across networks.

Docker

docker build -t excel-mcp-server .
docker run -p 8017:8017 -v "$PWD/workbooks:/data" -e EXCEL_MCP_AUTH_TOKEN=change-me excel-mcp-server

Configuration

Tools

Every parameter is documented in TOOLS.md.

Writing macros (opt-in)

With --allow-vba-write (or EXCEL_MCP_ALLOW_VBA_WRITE=1) the server can set the code of standard, class, workbook and sheet modules in .xlsm and .xltm files, delete standard and class modules, and create new .xlsm/.xltm workbooks. The server only stores the code; it never runs it, and Excel asks before enabling macros. Digitally signed VBA projects are refused, since any change would invalidate the signature.

Warning: macro code runs with your user's rights once you enable macros in Excel. A model that reads untrusted content could be tricked into writing harmful code. Enable this option only for trusted workflows, keep --allow-dir narrow, and read the code before you enable macros. The tools are never offered in --read-only mode.

Security

• Formulas are parsed before they are written. Functions that reach the network, other programs or host information (WEBSERVICE, HYPERLINK, IMAGE, RTD, CALL, INFO, INDIRECT, Google Sheets IMPORTXML and others), DDE links and references to other workbooks are rejected.
• Paths are resolved, including symlinks, before they are checked against the allowed folders.
• A single call processes at most 100,000 cells, and large reads are returned in pages.
• Cell contents are data from files. The server tells the model not to follow instructions found in them, but review what an assistant does with workbooks from untrusted sources.

Please report vulnerabilities privately; see SECURITY.md.

Limitations

• Formulas are stored in the file, and Excel calculates them when it opens it. So that read_range is useful before that, values mode calculates formulas that have no saved result with a built-in calculator (about 260 functions: math, statistics, financial and bond, dates, text, lookup, logical, LET, sorting and filtering). Results Excel saved are always preferred. A formula the calculator cannot reproduce exactly as Excel does (an unsupported function, a circular reference, or an Excel quirk it does not replicate) is returned as null and listed in uncalculated with the reason; it is never guessed. Ranges in a formula are reduced to the formula's own row or column where Excel's ordinary (not a