Excel MCP Server

Excel MCP 服务

一个开源的 Model Context Protocol（MCP）服务，可让 Claude、Cursor、VS Code Copilot、Codex 和其他 AI 客户端创建、读取和编辑 Excel 文件： 图表、数据透视表、公式、表格等。它基于 openpyxl 构建，无需 Microsoft Excel，并可在 Windows、macOS 和 Linux 上运行。

前往 excelmcpserver.com 安装并试用，或参阅下方的 快速入门。

功能

图表和数据透视表

• 使用 AI 创建 Excel 图表：柱形图、条形图、折线图、面积图、饼图、圆环图、雷达图、散点图和 气泡图，并支持组合图、次坐标轴、趋势线和误差线
• Excel 2016 图表类型：瀑布图、直方图、帕累托图、箱形图、树状图、旭日图和漏斗图
• 真正的 Excel 数据透视表（可刷新），支持分组、计算字段、“值显示方式”、 布局和筛选器；还支持数据透视表和表格的切片器与时间线
• 迷你图（折线、柱形、盈亏）

公式和动态数组

• 内置引擎可在不使用 Excel 的情况下计算公式（约 260 个函数，并通过超过 2,500 个来自真实 Excel 的公式进行验证），因此 read_range 可返回从未在 Excel 中打开过的文件的值
• 动态数组（FILTER、SORT、UNIQUE、SEQUENCE、LET）以 Excel 的存储方式保存，并溢出到相邻单元格
• 查明数值错误的原因：跨工作表、名称和表格追踪引用单元格和从属单元格，并像 Excel 的“公式求值”一样逐步计算公式
• 单变量求解：更改输入，直到公式达到所需值

数据、表格和规则

• 读取和写入单元格、日期和超链接；支持带汇总行和计算列的表格
• 条件格式（色阶、数据条、图标集、前/后排名、重复值、文本、日期）、数据验证（下拉列表、限制、输入消息）
• 排序、筛选（含条件）、查找和替换、删除重复项、分列、填充序列、选择性粘贴
• 字体、填充、边框、数字格式、合并单元格、冻结窗格、分组、打印设置、工作表保护、图片、备注和定义名称。插入或删除行列时，会像 Excel 一样更新所有引用

大型文件

• 读取时会流式处理工作簿并返回分页数据，因此即使工作表有数十万行，内存占用也保持稳定；每次调用都受大小和单元格数量限制
• 对 XML 达到或超过 1 MB 的工作表进行编辑时，只解析涉及的行，因此在包含 200,000 行的工作表中，插入或删除行列、排序、替换、复制工作表和创建数据透视表只需几秒，而不是几分钟

宏（可选启用）

• 读取 .xlsm 文件中的 VBA 代码。除非使用 --allow-vba-write 启动服务，否则无法写入 VBA；服务绝不会运行宏

安全设计

• 可选的文件夹限制、公式安全检查、只读模式、默认仅限 localhost 的 HTTP，以及不会留下半写入文件的原子保存

支持 .xlsx、.xlsm（保留宏）、.xltx 和 .xltm 文件。现有的线程化批注、形状、表单控件以及工具无法编辑的其他内容都会保持原样。

快速开始

你需要 uv。每个客户端都通过 uvx excel-mcp-server stdio 运行服务；将 /path/to/workbooks 替换为服务可以使用的文件夹。excelmcpserver.com 提供相同步骤，并带有复制按钮和适用于 Cursor 和 VS Code 的一键安装链接。

Claude Desktop（聊天）：从最新版本下载 excel-mcp-server.mcpb 并打开。Claude 会询问服务可以使用哪个文件夹。

Claude Code（命令行，以及 Claude Desktop 中的 Code 选项卡）：

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

Cursor（~/.cursor/mcp.json），以及大多数使用 mcpServers 配置的客户端：

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

VS Code（搭配 GitHub Copilot）（.vscode/mcp.json，注意 servers 键）：

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

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

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

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

桌面应用通常无法找到 uvx，因为它们看不到 Shell 的 PATH（macOS 上很常见）。请改用其完整路径，该路径可通过 which uvx 查看。

选择可供服务使用的文件

使用 --allow-dir DIR 后，服务只会打开 DIR 中的工作簿（包括子文件夹），且相对路径（如 reports/q1.xlsx）会以该目录为起点。重复使用此标志可允许多个文件夹，或者设置 EXCEL_FILES_PATH（在 macOS/Linux 上用 : 分隔文件夹，在 Windows 上用 ; 分隔）。

不使用 --allow-dir 时，任何 Excel 文件的绝对路径都有效。在所有模式下，服务只会处理 Excel 文件，并且绝不会在不提示的情况下覆盖现有工作簿。

远程使用（Streamable HTTP）

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

客户端连接到 http://127.0.0.1:8017/mcp。工作簿位于 --allow-dir 文件夹中（默认为 ./excel_files），export_workbook / import_workbook 会在服务与客户端之间传输文件。

服务仅监听 localhost。若要接受其他机器的连接，请设置令牌和主机：

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

客户端随后发送 Authorization: Bearer change-me。若要通过网络使用，请在其前面配置一个用于终止 TLS 的反向代理。

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

配置

工具

选择工具

每个工具都会在每次请求中占用上下文。--tools 仅提供核心工具 （describe_workbook、describe_sheet、read_range）以及你列出的区域，例如 uvx excel-mcp-server stdio --tools data,charts。它可与 --read-only（指定区域的只读工具） 和 --allow-vba-write（还需要 vba 区域）组合使用。未知区域会导致服务在启动时停止，并列出有效区域。以下大小以字符数表示工具描述和架构的长度，每个词元约对应 3.5 个字符：

CSV

import_csv 会将 .csv 或 .tsv 文件导入工作表中的指定单元格（如果工作表不存在，则会创建），而 export_csv 会将一个区域写出为 CSV。两者都只会在允许的文件夹中操作，不会超出 --max-cells 和 --max-file-mb 的限制，也绝不会运行任何内容。

• 导入时会根据第一条记录检测分隔符（也可以指定 comma、semicolon、tab、 pipe），并读取带或不带 BOM 的 UTF-8、UTF-16 和 cp1252。引号括起的字段及其中的换行符 都会保留。
• 字段会按 Excel 导入时的规则设置类型：数字（包括 1,234.50、12%；小数逗号格式请用 decimal）、TRUE/FALSE 和 ISO 日期（2026-01-31、2026-01-31 09:30）会转换为值。Excel 会改动的文本则会保留为文本：前导零（007）、超过 15 位的数字、前导 +，以及数字日期（如 01/02/2026）；数字日期仅会按你指定的 date_order（dmy 或 mdy）读取。as_text 会将所有字段都保留为文本。
• 字段绝不会作为公式处理。以 =、+、- 或 @ 开头的文本会通过 Excel 的引号前缀存储为文本，因此编辑单元格时不会运行它；像 -5 这样的数字则仍是数字。
• 导出时会写出原始值（完整精度、ISO 日期），或者使用 formatted 写出 Excel 中显示的内容。以 =、+、- 或 @ 开头的文本单元格会添加 ' 前缀（默认启用 escape_formulas），避免打开文件的电子表格运行这些内容；数字绝不会添加前缀。 日期时间会写为 2026-01-31T09:30:00，Excel 会将其作为文本打开；要导出为 Excel 格式，请使用 formatted。 使用 encoding: utf-8-sig 添加 BOM；Excel 通过双击打开 UTF-8 文件时需要它才能正确显示重音字符。行尾为 CRLF。

每个参数都在 TOOLS.md 中有说明。所有工具中的参数含义相同：

更改工作簿的工具会返回所做更改的信息（sheet、range、name），以便下一次调用引用这些内容。图表和图像按名称选择，名称列于 describe_sheet 中。

编写宏（选择启用）

启用 --allow-vba-write（或设置 EXCEL_MCP_ALLOW_VBA_WRITE=1）后，服务可以在 .xlsm 和 .xltm 文件中设置标准模块、类模块、工作簿模块和工作表模块的代码，删除标准模块和类模块，并创建新的 .xlsm/.xltm 工作簿。服务只会存储代码，绝不会运行代码；启用宏前，Excel 会向你确认。对于经过数字签名的 VBA 项目，服务会拒绝操作，因为任何更改都会使签名失效。

警告：在 Excel 中启用宏后，宏代码会以你的用户权限运行。读取不可信内容的模型可能会被诱骗写入有害代码。仅在可信工作流中启用此选项，将 --allow-dir 的范围设得尽可能窄，并且启用宏前请先阅读代码。在 --read-only 模式下，绝不会提供这些工具。

安全性

• 公式会在写入前进行解析。会访问网络或其他程序的函数（WEBSERVICE、IMAGE、RTD、CALL、Google Sheets 的 IMPORTXML 等）、Excel 4.0 宏函数（FILES、GET.WORKBOOK、RUN 等）、DDE 链接以及对其他工作簿的引用都会被拒绝。HYPERLINK 仅在链接固定为 http(s)://、mailto: 或 #Sheet!A1 时才会被接受。
• 路径会在检查是否位于允许的文件夹中之前进行解析，包括解析符号链接。网络路径（UNC）和 Windows 设备路径一律拒绝。
• 单次调用最多处理 100,000 个单元格（--max-cells），大型读取结果会分页返回。
• 单元格内容是来自文件的数据。服务会告知模型不要遵循其中的指令，但请留意助手如何处理来自不可信来源的工作簿。

请私下报告漏洞；详情请参阅 SECURITY.md。

限制

• 公式存储在文件中，Excel 会在打开文件时计算公式。因此，在这之前，read_range 会很有用；values 模式会使用内置计算器计算没有已保存结果的公式（约 260 个函数：数学、统计、财务与债券、日期、文本、查找、逻辑、LET、排序和筛选）。始终优先使用 Excel 保存的结果。对于计算器无法像 Excel 那样精确复现的公式（例如不支持的函数、循环引用，或计算器未复现的 Excel 特性），结果会返回 null，并在 uncalculated 中列出原因；绝不会猜测结果。如果 Excel 的普通公式（非数组公式）对公式所在行或列采用相同处理，公式中的区域会缩减为公式所在的行或列；此外，不会计算 RAND 等易变函数。计算器已使用从真实 Excel 记录的 2,500 多个公式进行验证（tests/fixtures/formula_golden.json）。
• trace_formula 和 goal_seek 使用该计算器，因此 goal_seek 会拒绝无法计算的公式。Excel 的“追踪从属单元格”会显示 OFFSET 起始引用的单元格，而 trace_formula 会显示 INDIRECT 和 OFFSET 指向的单元格；如果无法确定这些单元格，公式会列在 unknown 中。当 Excel 的搜索因显示“可能未找到解”而停止时，goal_seek 仍可能找到根，并且只有在收敛时才会保存答案（与 Excel 一样，误差不超过目标值的 0.001）。
• Excel 在 2007 年后新增的函数（IFS、XLOOKUP、STDEV.S、SORT……）在存储公式的任何位置（单元格、复制和排序后的单元格、条件格式、数据验证、定义名称）都会使用 Excel 要求的 _xlfn. 前缀。
• 不支持旧版 .xls 文件；CSV 文件请使用 import_csv。
• 数据透视表基于快照创建，可使用最多包含 3,000,000 个单元格的文本、数字和日期列（--max-pivot-cells）；Excel 会根据实时源数据刷新数据透视表。它们支持数字格式、“值显示方式”（占总计、行、列或父级的百分比、与……的差异、累计总计、排名）、按标签或值排序、日期和数字分组、计算字段、紧凑、大纲和表格布局、启用或禁用小计、按选定项目筛选，以及将多个值字段显示为列或行。写入单元格的数字是 Excel 刷新后显示的数字；这些数字已与从真实 Excel 记录的约 200 个数据透视表进行核对（tests/fixtures/pivot_golden.json）。例外情况：按值排序时并列的项目在刷新后可能互换位置；values_in: "rows" 不能与排名数据组合，也不能在有小计时与字段上的其他数据组合，因为 Excel 会在此处混淆值字段。
• add_slicer 可为表格和数据透视表添加切片器（插入 > 切片器），也可为数据透视表的日期字段添加时间线：字段、标题、位置和大小、列数、样式、排序、选定项目（或时间段）以及“隐藏没有数据的项目”。选择项目会像点击操作一样进行筛选：表格行会被筛选并隐藏；数据透视表项目会被隐藏，并根据源数据重新计算数字，Excel 刷新时会确认这些数字（约 200 个数据透视表已与 Excel 核对，切片器变体也已与 Excel 自身的结果核对）。一个切片器可以筛选共享同一缓存的多个数据透视表，例如复制工作表中的数据透视表。限制：由 Excel 创建或刷新的数据透视表会在单元格中保留数字（隐藏项目和打开时刷新标记都会被存储，因此 Excel 打开文件时会重新计算）；数据透视表中分组的字段不能使用切片器。
• 插入或删除行和列，以及重命名工作表时，引用会像在 Excel 中一样更新。超链接目标和 3D 引用（Sheet1:Sheet3!A1）保持不变（Excel 也会这样处理）。如果编辑操作穿过数组公式、数据透视表、表格标题，或同时穿过两个表格，则会被拒绝。插入的单元格会沿用上方或左侧行列的格式、行高和列宽（首行或首列没有可沿用的内容）；在表格中插入行时，计算列会填充到新行中。
• 编辑工作簿时，工具无法修改的内容会保留：迷你图、扩展条件格式和数据验证、切片器和时间线、较新的图表（水滴图、直方图、树状图等）、线程化批注、形状、表单控件、链接数据类型和自定义 XML 都会保持 Excel 保存时的状态，并随插入或删除的行和列以及重命名的工作表移动。copy_sheet 会像 Excel 一样复制迷你图、切片器和时间线、条件格式中适用于 Excel 2010 的部分（数据条、图标集），以及由 create_chart 创建的 Excel 2016 图表，但不会复制其他内容。删除工作表时，只删除仅由该工作表使用的切片器；如果切片器将失去其数据透视表，则会阻止删除；删除表格，或删除表格切片器所筛选的列时，也会移除该切片器。 数字签名会被移除，这与 Excel 修改已签名文件时的处理方式一致。
• 返回多个值的公式（FILTER、SORT、UNIQUE、SEQUENCE、A2:A9*2）会像在 Excel 中一样存储为动态数组公式，并溢出到相邻单元格。若单元格阻挡溢出，溢出会受阻（Excel 会显示 #SPILL!），并由 write_range 报告。如果计算器无法确定结果的大小，则只存储公式所在的单元格，Excel 打开文件时会填充其余单元格。

从 1.x 升级

2.0 版本统一了各个工具的工具名称和参数名称，因此会导致 1.x 客户端和已保存的提示词无法正常使用。变更日志中有一张表，列出了所有 1.x 名称及其对应的 2.0 替代名称： 从 1.x 升级。从 0.x 升级？请先查看 1.0.0 说明。

贡献

欢迎贡献。请参阅 CONTRIBUTING.md。

许可证

MIT。请参阅 LICENSE。