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 and dates, with paging for large sheets and search
• Format fonts, fills, borders, number formats, column widths and frozen panes
• Structure sheets, rows and columns, merged cells, tables, charts and summary tables
• Rules: conditional formatting and data validation (dropdowns, number limits)
• Macros: read the VBA code in .xlsm files, module by module (read-only, never run)
• 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, 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
--max-file-mb N		100	Largest workbook the server opens
--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, list_workbooks, export_workbook, import_workbook
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, find_cells
Formatting	format_range, merge_cells, set_sheet_layout, add_conditional_format, add_data_validation
Objects	create_table, create_chart, create_summary_table
Macros	read_vba

Every parameter is documented in TOOLS.md.

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, not calculated. read_range in values mode returns the results Excel last saved, so formulas written by this server read as empty until the file is opened and saved in Excel or LibreOffice.
• Legacy .xls and .csv files are not supported.
• create_summary_table writes a static summary; openpyxl cannot create real PivotTables.
• Inserting or deleting rows and columns does not update formulas, charts or tables that refer to the moved cells.
• Workbook features openpyxl does not understand, such as shapes, slicers and some embedded objects, may be lost when a workbook is edited. Pictures, charts, tables and macros in .xlsm files are kept.

Upgrading from 0.x

Version 1.0 renames and redesigns the tools, removes the SSE transport and requires Python 3.11 or newer. The changelog maps every old tool to its replacement.

Contributing

Contributions are welcome. See CONTRIBUTING.md.

Star history

License

MIT. See LICENSE.