Excel MCP Server

Excel MCP Server

An open-source Model Context Protocol ↗ (MCP) server that lets

Claude, Cursor, VS Code Copilot, Codex and other AI clients create, read and edit Excel files:

charts, PivotTables, formulas, tables and more. It is built on openpyxl, needs **no Microsoft

Excel**, and runs on Windows, macOS and Linux.

Install and try it at excelmcpserver.com ↗, or see

Quick start below.

Features

Charts and PivotTables

• Create Excel charts with AI: column, bar, line, area, pie, doughnut, radar, scatter and

bubble, with combos, secondary axes, trendlines and error bars

• The Excel 2016 chart types: waterfall, histogram, Pareto, box and whisker, treemap, sunburst

and funnel

• Real PivotTables that Excel refreshes (grouping, calculated fields, "show values as",

layouts, filters), plus slicers and timelines for PivotTables and tables

• Sparklines (line, column, win/loss)

Formulas and dynamic arrays

• Formulas are calculated without Excel by a built-in engine (about 260 functions, checked

against more than 2,500 formulas recorded from real Excel), so read_range returns values

for files that were never opened in Excel

• Dynamic arrays (FILTER, SORT, UNIQUE, SEQUENCE, LET) are stored as Excel stores

them and spill into the cells next to them

• Find out why a number is wrong: trace precedents and dependents across sheets, names and

tables, and evaluate a formula step by step as Excel's Evaluate Formula does

• Goal Seek: change an input until a formula reaches the value you want

Data, tables and rules

• Read and write cells, dates and hyperlinks; tables with totals rows and calculated columns
• Conditional formatting (scales, data bars, icon sets, top/bottom, duplicates, text, dates),

data validation (dropdowns, limits, input messages)

• Sort, filter (with criteria), find and replace, remove duplicates, text to columns, fill

series, paste special

• Fonts, fills, borders, number formats, merged cells, frozen panes, grouping, print setup,

sheet protection, images, notes and defined names. Inserting or deleting rows and columns

updates every reference, as in Excel

Large files

• Reads stream the workbook and return pages, so memory stays flat on sheets with hundreds of

thousands of rows; every call is bounded by size and cell limits

• Edits of a sheet of 1 MB of XML or more parse only the rows they touch, so inserting or

deleting rows and columns, sorting, replacing, copying a sheet and creating a PivotTable

take seconds on a 200,000-row sheet instead of minutes

Macros (opt-in)

• Read the VBA code in .xlsm files. Writing VBA is off unless you start the server with

--allow-vba-write; the server never runs macros

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. Existing

threaded comments, shapes, form controls and other content the tools cannot edit are kept as

they are.

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. excelmcpserver.com ↗ has the same steps with copy

buttons and one-click install links for Cursor and VS Code.

Claude Desktop (Chat): download

excel-mcp-server.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, Gemini CLI, Devin Desktop, and Claude Desktop without the bundle

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

· Flag · Environment variable · Default · Meaning ·

· --allow-dir DIR · EXCEL_FILES_PATH · none (stdio), ./excel_files (HTTP) · Folders workbooks must be in ·

· --read-only · EXCEL_MCP_READ_ONLY=1 · off · Only offer tools that do not change files ·

· --allow-vba-write · EXCEL_MCP_ALLOW_VBA_WRITE=1 · off · Add tools that write VBA macros (see warning below); ignored with --read-only ·

· --tools AREAS · EXCEL_MCP_TOOLS · all · Only offer the core tools and these comma-separated areas, to save context (see Choosing tools) ·

· --max-file-mb N · EXCEL_MCP_MAX_FILE_MB · 100 · Largest workbook the server opens. Also sets the unpacked-size limit (10 times this) that every opened or uploaded workbook must stay under; parts compressed over 500:1 are refused ·

· --max-cells N · EXCEL_MCP_MAX_CELLS · 100000 · Most cells one call may read, write or format; reads are still returned in pages ·

· --max-pivot-cells N · EXCEL_MCP_MAX_PIVOT_CELLS · 3000000 · Largest PivotTable source in cells (a 230,000-row, 13-column sheet); creating one from the biggest sources takes a minute and about 2 GB of memory ·

· --max-loaded-cells N · EXCEL_MCP_MAX_LOADED_CELLS · 3000000 · Most cells and rows of a workbook that may be loaded into memory at once, about 0.5 KB each (a 3,000,000 limit is about 1.5 GB). A workbook with more is refused by the tools that must load whole sheets; read_range and the other streaming reads, and edits of large sheets that parse only some rows, are not limited by the size of the sheet ·

· --log-level LEVEL · · WARNING · Logging on stderr ·

· --host HOST · EXCEL_MCP_HOST · 127.0.0.1 · HTTP listen address ·

· --port PORT · EXCEL_MCP_PORT · 8017 · HTTP port ·

· · EXCEL_MCP_AUTH_TOKEN · none · Bearer token required on HTTP requests ·

· --allow-unauthenticated · · off · Allow a non-local --host without a token ·

Tools

· Area · Tools ·

· Workbooks · create_workbook, describe_workbook, set_workbook_settings, list_workbooks, export_workbook, import_workbook ·

· CSV · import_csv, export_csv ·

· Sheets · describe_sheet, create_sheet, rename_sheet, copy_sheet, delete_sheet, insert_rows_or_columns, delete_rows_or_columns ·

· Cells · read_range, write_range, clear_range, copy_range, sort_range, transform_range, find_cells, replace_cells ·

· Formulas · trace_formula, goal_seek ·

· Formatting · format_range, merge_cells, set_sheet_layout, add_conditional_format, add_data_validation ·

· Objects · set_table, create_chart, delete_chart, create_pivot_table, delete_pivot_table, add_slicer, delete_slicer, insert_image, delete_image, add_sparklines, delete_sparklines ·

· Names and notes · set_defined_name, delete_defined_name, set_note, delete_note ·

· Macros · read_vba; with --allow-vba-write: write_vba_module, delete_vba_module ·

Choosing tools

Every tool costs context in every request. --tools offers only the core tools

(describe_workbook, describe_sheet, read_range) and the areas you list, for example

uvx excel-mcp-server stdio --tools data,charts. It combines with --read-only (read-only tools

of the areas) and --allow-vba-write (which also needs the vba area). An unknown area stops the

server at startup and lists the valid ones. The sizes are characters of tool descriptions and

schemas, at about 3.5 characters per token:

· Area · Tools · Characters ·

· core (always) · describe_workbook, describe_sheet, read_range · 8,900 ·

· workbooks · create_workbook, set_workbook_settings, list_workbooks, export_workbook, import_workbook · 2,600 ·

· csv · import_csv, export_csv · 2,200 ·

· sheets · create_sheet, rename_sheet, copy_sheet, delete_sheet, insert_rows_or_columns, delete_rows_or_columns · 2,000 ·

· data · write_range, clear_range, copy_range, sort_range, transform_range, find_cells, replace_cells · 6,700 ·

· formulas · trace_formula, goal_seek · 1,300 ·

· formatting · format_range, merge_cells, set_sheet_layout, add_conditional_format, add_data_validation · 14,000 ·

· tables · set_table · 1,900 ·

· charts · create_chart, delete_chart, add_sparklines, delete_sparklines · 9,900 ·

· pivots · create_pivot_table, delete_pivot_table · 4,600 ·

· slicers · add_slicer, delete_slicer · 2,500 ·

· names · set_defined_name, delete_defined_name · 900 ·

· notes · set_note, delete_note · 500 ·

· images · insert_image, delete_image · 800 ·

· vba · read_vba; with --allow-vba-write: write_vba_module, delete_vba_module · 1,900 ·

CSV

import_csv reads a .csv or .tsv file into a sheet (created if missing) at a cell, and

export_csv writes a range as CSV. Both stay in the allowed folders, within --max-cells and

--max-file-mb, and never run anything.

• Import detects the delimiter from the first record (or takes comma, semicolon, tab,

pipe) and reads UTF-8 with or without a BOM, UTF-16 and cp1252. Quoted fields and line

breaks inside them are kept.

• Fields are typed as in Excel's import: numbers (also 1,234.50, 12%; decimal for a

decimal comma), TRUE/FALSE and ISO dates (2026-01-31, 2026-01-31 09:30) become values.

Text Excel would alter stays text: leading zeros (007), more than 15 digits, a leading +,

and numeric dates such as 01/02/2026, which are read only in the date_order you name

(dmy or mdy). as_text keeps every field as text.

• Fields are never formulas. Text starting with =, +, - or @ is stored as text with

Excel's quote prefix, so editing the cell does not run it; a number such as -5 is a number.

• Export writes raw values (full precision, ISO dates) or, with formatted, what Excel shows.

Text cells starting with =, +, - or @ get a ' prefix (escape_formulas, on by

default) so a spreadsheet that opens the file does not run them; numbers are never prefixed.

Datetimes are written as 2026-01-31T09:30:00, which Excel opens as text; use formatted

for Excel.

Use encoding: utf-8-sig for a BOM, which Excel needs to show accents when it opens a UTF-8

file by double-click. Lines end with CRLF.

Every parameter is documented in TOOLS.md ↗. Parameters mean the same in every tool:

· Parameter · Meaning ·

· path, sheet · The workbook and the worksheet ·

· range, at · A block of cells (A1:D20), and the top-left cell of whatever is placed there: written values, copies, charts, images, PivotTables, slicers ·

· source · Where data comes from, optionally on another sheet (Data!A1:E200) ·

· name · The name of a table, chart, image, PivotTable, slicer or defined name ·

· _cm, _pt, _chars · Units of sizes: width_cm, row_heights_pt, column_widths_chars ·

Tools that change a workbook return what they changed (sheet, range, name) so that the

next call can refer to it. Charts and images are selected by name, as listed by describe_sheet.

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 or other

programs (WEBSERVICE, IMAGE, RTD, CALL, Google Sheets IMPORTXML and others),

Excel 4.0 macro functions (FILES, GET.WORKBOOK, RUN and others), DDE links and

references to other workbooks are rejected. HYPERLINK is accepted with a fixed

http(s)://, mailto: or #Sheet!A1 link only.

• Paths are resolved, including symlinks, before they are checked against the allowed

folders. Network (UNC) and Windows device paths are always rejected.

• A single call processes at most 100,000 cells (--max-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 array-entered) formulas do the same, and volatile functions such as RAND are not

calculated. The calculator is checked against more than 2,500 formulas recorded from real

Excel (tests/fixtures/formula_golden.json).

• trace_formula and goal_seek use that calculator, so goal_seek refuses a formula it

cannot calculate. Where Excel's Trace Precedents shows the cells an OFFSET starts from,

trace_formula shows the cells INDIRECT and OFFSET point at; when those cannot be

worked out the formula is listed in unknown. Where Excel's search stops at the

"may not have found a solution" message, goal_seek may still find a root, and it stores

the answer only when it converges (within 0.001 of the target, as Excel does).

• Functions Excel added after 2007 (IFS, XLOOKUP, STDEV.S, SORT, ...) are written

with the _xlfn. prefix Excel expects, wherever formulas are stored (cells, copied and

sorted cells, conditional formats, data validation, defined names).

• Legacy .xls files are not supported; use import_csv for CSV files.
• PivotTables are created from a snapshot and can use text, number and date columns of up to

3,000,000 cells (--max-pivot-cells); Excel refreshes them from the live source data. They support number formats,

"show values as" (percent of total, row, column or parent, difference from, running total,

rank), sorting by label or value, date and number grouping, calculated fields, compact,

outline and tabular layouts, subtotals on or off, filters with chosen items and several

value fields as columns or rows. The figures written into the cells are the ones Excel shows

after a refresh, checked against about 200 PivotTables recorded from real Excel

(tests/fixtures/pivot_golden.json). The exceptions: items that tie when sorted by value may

swap places on refresh, and values_in: "rows" cannot be combined with rank figures or, with

subtotals, other figures along a field, because Excel mixes the value fields up there.

• add_slicer adds slicers (Insert > Slicer) for tables and PivotTables, and timelines for date

fields of PivotTables: field, caption, position and size, columns, style, sort, selected

items (or a period) and "hide items with no data". Selecting items filters as clicking

does: table rows are filtered and hidden; PivotTable items are hidden and the figures

recalculated from the source, which Excel confirms on refresh (about 200 PivotTables are

checked against Excel, and the slicer variants against Excel's own results). One slicer can

filter several PivotTables that share a cache, such as those of copied sheets. Limits: a

PivotTable made or refreshed by Excel keeps its figures in the cells (the hidden items and

a refresh-on-open mark are stored, so Excel recalculates when it opens the file); fields

grouped in a PivotTable take no slicer.

• Inserting or deleting rows and columns, and renaming a sheet, update references like

Excel. Hyperlink targets and 3D references (Sheet1:Sheet3!A1) are left alone (Excel does

the same). An edit that cuts through an array formula, a PivotTable, a table header or two

tables at once is refused. Inserted cells take the formatting, row height and column width

of the line above or to the left (nothing at the first row or column), and calculated table

columns are filled into rows inserted in a table.

• Editing a workbook keeps what the tools cannot change: sparklines, extended conditional

formats and validation, slicers and timelines, newer charts (waterfall, histogram,

treemap and others), threaded comments, shapes, form controls, linked data types and

custom XML stay as Excel saved them and move with inserted or deleted rows and columns and

renamed sheets. copy_sheet copies sparklines, slicers and timelines (as Excel does), the Excel

2010 half of conditional formats (data bars, icon sets) and the Excel 2016 charts made by

create_chart, but not the others. Deleting a sheet removes slicers that only it used;

slicers that would be left without their PivotTable block the deletion, and deleting a

table, or the column a table slicer filters, removes the slicer.

Digital signatures are removed, as Excel does when a signed file changes.

• Formulas that return several values (FILTER, SORT, UNIQUE, SEQUENCE, A2:A9*2) are

stored as dynamic array formulas, as Excel stores them, and spill into the cells next to

them. A cell in the way blocks the spill (Excel shows #SPILL!), and write_range

reports it. Where the calculator cannot tell how large a result is, only the formula's

cell is stored and Excel fills in the rest when it opens the file.

Upgrading from 1.x

Version 2.0 makes tool and parameter names consistent across tools, which breaks 1.x clients

and saved prompts. The changelog has a table that maps every 1.x name to its 2.0 replacement:

Upgrading from 1.x ↗. Coming from 0.x? See the

1.0.0 notes ↗ first.

Contributing

Contributions are welcome. See CONTRIBUTING.md ↗.

License

MIT. See LICENSE ↗.