内容
# ThepExcelMCP
一个通过 COM（使用 pywin32）驱动实时运行的 Excel 桌面实例的 Windows MCP 服务器，为 AI 代理提供完整的 Excel 功能，这是仅靠文件库无法实现的。当代理调用此处的一个工具时，它正在与实际的 Excel 进程进行对话 - Power Query 查询会针对实时数据源刷新，数据透视表会使用真实聚合重新构建，图表会渲染为 PNG 以进行视觉验证，DAX 度量会在内存数据模型中执行，动态数组溢出范围会正确解析。这是编辑 XML zip 文件和使用 Excel 之间的区别。
## 快速开始 - 交给您的 AI 代理
只需将此 GitHub 链接发送给您的 AI 编码代理（Claude Code、Codex CLI 等），并告诉它接管 - 它将读取此 README 并为您设置 MCP 服务器，无论是**用户范围**（在每个项目中都可用）还是**项目范围**（仅限一个项目）。
> 🇹🇭 แค่ส่งลิงก์ GitHub นี้ให้ AI Agent ของคุณ แล้วบอกให้ AI จัดการต่อได้เลย จะลง MCP เป็น User Scope หรือ Project Scope ก็ได้
```
https://github.com/ThepExcel/ThepExcelMCP
```
## 它如何运行 - 本地运行，而不是托管服务
ThepExcelMCP 是一个 **stdio MCP 服务器，作为您自己的 Windows 机器上的进程运行**，并控制在那里运行的 Excel。该服务器没有任何注册要求，无需账户，且不会有数据离开您的计算机。可从可以在同一台机器上启动本地 stdio 服务器的任何 MCP 客户端使用：
- ✅ **Claude Code**、**Claude Desktop** 和 **Codex CLI** 可以本地运行并启动它。
- ❌ 仅限云端的代理界面，无法在您的机器上运行本地进程 - 例如 **Claude Cowork** 目前无法访问您的本地 Excel，因此无法使用它。
## 为什么使用 COM 而不是文件库？
像 `openpyxl` 这样的库可以读写 `.xlsx` 文件，但它们**无法操作 Excel**。ThepExcelMCP 驱动真正的应用程序，因此 AI 可以**从空白工作簿创建完整的解决方案** - 不仅仅是修改已经存在的文件：
- **一次性构建整个数据管道。** 将 AI 交付一个空白的工作簿，它可以*编写* M 中的 Power Query，从头开始，合并和转换多个源，将结果加载到工作表表格中，然后在上面构建数据透视表和图表 - 整个流程，从头到尾。刷新现有的查询是微不足道的；这*创建*查询、表格和数据透视表。
- **Power Query，完全可编辑。** 读取和重写任何现有查询的 M，创建和设置查询参数，针对实时数据源刷新，并加载到工作表表格或直接加载到数据模型。（文件库无法评估 M 代码。）
- **数据模型和 DAX（Power Pivot）实际计算。** 添加模型表格和关系，编写和更新 DAX 度量，并让 Excel 的内存引擎计算它们 - 以及 CUBEVALUE / CUBEMEMBER 助手。
- **真正的数据透视表。** 从范围、表格或数据模型中；添加、移动和删除具有真实聚合的字段；设置布局和刷新 - Excel 计算的每个值，而不是近似值。
- **实时重新计算。** 动态数组溢出公式（`XLOOKUP`、`SORT`、`FILTER`）、易失性函数和普通公式由 Excel 的计算引擎评估，并且可以读取溢出的结果。
- **Excel 中的 Python。** 插入在 Excel 的 Python 运行时环境中运行的 `=PY()` 公式。
- **图表、格式和视觉层** - 以及捕获任何范围、工作表或图表为 PNG，以便 AI 可以*看到*它刚刚构建的内容并进行验证。
- **VBA 和完整的对象模型。** 运行宏并访问 COM 公开的任何内容。
- **安全网。** 在冒险自动化之前拍摄非破坏性快照，并对比两个范围或工作表以查看实际更改的内容。
## 需求
- Windows 10 或 11
- Microsoft 365 Excel 桌面版（Excel 必须在**首次工具调用前运行**，或设置 `THEPEXCEL_MCP_AUTOLAUNCH=1`）
- [uv](https://docs.astral.sh/uv/) - 一个快速的 Python 包管理器。它为您安装和管理正确的 Python 版本，因此您**不需要**单独安装 Python。如果您还没有：
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
或通过 winget：`winget install --id=astral-sh.uv -e`。关闭并重新打开您的终端，以便 `uv` 出现在您的 PATH 中。
## 平台支持
该服务器通过 Windows COM（`pywin32`）驱动一个**真正的 Excel 进程**，因此它**仅限于 Windows**：
- ✅ **Windows 10 / 11** - 完全支持。
- ❌ **macOS** - 不支持。Excel for Mac 不公开 COM 自动化 API，而 `pywin32` 不存在于 macOS 上。没有变通方法；这是硬件平台限制，而不是缺少的功能。
- ⚠️ **WSL（Windows 子系统 Linux）** - 服务器**无法在 WSL 中运行**，因为 WSL 中的 Linux Python 没有 `pywin32`，并且没有路径访问 Windows COM。但是，如果您的 MCP 客户端（例如 Claude Code）在 WSL 中运行，您仍然可以通过在 WSL ↔ Windows 互操作边界上运行它作为**原生 Windows 进程**来使用服务器：
1. 在 **Windows** 文件系统（例如 `C:\Tools\ThepExcelMCP`）上克隆并 `uv sync` 仓库，使用 Windows `uv` - 而不是在 WSL 文件系统中。
2. 从您的 WSL 客户端注册服务器，以便命令是 Windows `uv.exe` 指向该 Windows 检出：
```bash
claude mcp add thepexcel-excel --scope user -- \
uv.exe run --directory 'C:\Tools\ThepExcelMCP' thepexcel-mcp
```
stdio 管道桥接 WSL→Windows 进程边界；服务器进程和 Excel 都在 Windows 上原生运行。Excel 必须在您的 **Windows** 桌面会话中打开（WSLg / Linux GUI Excel 将不起作用）。
此 WSL 路径在底层 Windows 上运行相同的代码 - 它作为指导提供，而不是单独测试的安装模式。支持的、没有惊喜的设置是纯 Windows。
## 安装
```bash
git clone https://github.com/ThepExcel/ThepExcelMCP.git
cd ThepExcelMCP
uv sync
```
`uv sync` 安装 `fastmcp`、`pywin32` 和 `pillow` 到隔离的虚拟环境中。不需要 pip 或手动 virtualenv 设置。
## 与 Claude Code（CLI）注册
```bash
claude mcp add thepexcel-excel --scope user -- uv run --directory /path/to/ThepExcelMCP thepexcel-mcp
```
在 Windows 上，路径将如下所示：
```powershell
claude mcp add thepexcel-excel --scope user -- uv run --directory C:\path\to\ThepExcelMCP thepexcel-mcp
```
验证服务器出现并干净地启动：
```bash
claude mcp list
```
要启用 VBA 并在启动时自动启动 Excel，请传递环境变量：
```powershell
claude mcp add thepexcel-excel --scope user `
-e THEPEXCEL_MCP_AUTOLAUNCH=1 `
-e THEPEXCEL_MCP_ENABLE_VBA=1 `
-- uv run --directory C:\path\to\ThepExcelMCP thepexcel-mcp
```
## 与 Claude Desktop 注册
编辑 `%APPDATA%\Claude\claude_desktop_config.json`：
```json
{
"mcpServers": {
"thepexcel-excel": {
"command": "uv",
"args": ["run", "--directory", "C:\\path\\to\\ThepExcelMCP", "thepexcel-mcp"],
"env": {
"THEPEXCEL_MCP_AUTOLAUNCH": "1"
}
}
}
}
```
保存后重启 Claude Desktop。服务器在您第一次调用 Excel 工具时按需启动。
## 与 Codex CLI 注册
Codex 通过相同的 stdio 传输与 MCP 服务器通信，因此服务器保持不变。`codex mcp add` 写入您的**用户范围**配置（`~/.codex/config.toml`），使服务器在每个 Codex 项目中都可用：
```powershell
codex mcp add thepexcel-excel --env THEPEXCEL_MCP_AUTOLAUNCH=1 -- uv run --directory C:\path\to\ThepExcelMCP thepexcel-mcp
```
验证它已注册：
```powershell
codex mcp list
codex mcp get thepexcel-excel
```
`~/.codex/config.toml` 的等效手动编辑：
```toml
[mcp_servers.thepexcel-excel]
command = "uv"
args = ["run", "--directory", "C:\\path\\to\\ThepExcelMCP", "thepexcel-mcp"]
[mcp_servers.thepexcel-excel.env]
THEPEXCEL_MCP_AUTOLAUNCH = "1"
```
如果您不想让 Excel 自己启动，请删除 `[mcp_servers.thepexcel-excel.env]` 表。
### 项目范围（仅限一个项目）
要将服务器范围限定为单个项目而不是全局，请将相同的 `[mcp_servers.thepexcel-excel]` 块添加到该项目根目录的 `.codex/config.toml` 文件中。两个注意事项：
- `codex mcp add` 始终写入**用户**配置 - 没有 CLI 标志用于项目范围，因此请手动创建/编辑 `.codex/config.toml`。
- Codex 必须**信任项目**，并且您必须从该项目根目录启动 Codex。项目范围的服务器在 **CLI** 上加载；Codex **Desktop** 目前忽略项目 `.codex/config.toml` 而只读取用户配置（[openai/codex#13025](https://github.com/openai/codex/issues/13025））。
重启 Codex 会话后编辑配置 - MCP 工具会在会话启动时加载。
## 工具
总共有 **26 种工具**，按类别组织。
### 核心
| 工具 | 操作 | 描述 |
|------|---------|-------------|
| `excel_workbook` | list, info, open, save, close, create, save_as | 管理打开的工作簿：发现、打开、创建、保存、另存为和关闭。 |
| `excel_sheet` | list, add, rename, delete | 管理工作簿中的工作表：列表、添加、重命名、删除。 |
| `excel_range` | read, read_spill, write, write_formula, write_py, clear | 读取和写入单元格范围，包括动态数组溢出和 Excel 中的 Python 公式。 |
### 数据 / Power Query / 数据模型
| 工具 | 操作 | 描述 |
|------|---------|-------------|
| `excel_powerquery` | list, get, create, update, delete, refresh, refresh_all, load_to_table, load_to_datamodel, analyze, analyze_raw, create_parameter, get_parameter, set_parameter, list_parameters | 管理 Power Query（M 代码）查询：CRUD、刷新、加载到表格/模型、分析以及参数操作。 |
| `excel_table` | list, create, read, append_rows, add_column, sort, filter, set_style, toggle_totals, rename, delete | 管理 Excel 表（ListObjects）：创建、读取、追加、添加列、排序、筛选、样式、总计、重命名、删除。 |
| `excel_pivot` | list, create, add_field, remove_field, move_field, set_layout, refresh, delete, read | 管理数据透视表：创建、添加/删除/移动字段、设置布局、刷新、读取和删除。 |
| `excel_datamodel` | info, list_tables, add_table, list_relationships, add_relationship, delete_relationship, list_measures, add_measure, update_measure, delete_measure, refresh, cube_formula, cube_value, cube_member, add_calculated_column, add_calculated_table | 管理 Excel 数据模型（Power Pivot）：表格、关系、DAX 度量和 CUBE 公式助手。 |
| `excel_name` | list, get, set, delete | 管理定义名称：命名范围、常量和 LAMBDA 公式。 |
### 对象
| 工具 | 操作 | 描述 |
|------|---------|-------------|
| `excel_chart` | list, create, configure, set_source, export_image, delete | 创建和管理嵌入式图表：创建、配置、更改源、导出 PNG、删除。 |
| `excel_shape` | add_image, add_textbox, add_shape, list, move, delete | 添加和管理绘图对象（图像、文本框、AutoShapes）：添加、列表、移动、删除。 |
| `excel_slicer` | add, add_timeline, list, delete, connect | 管理数据透视表和表格的切片器和日期时间线：添加、添加时间线、列表、删除、连接。 |
| `excel_sparkline` | add, clear, list | 添加、清除和列表单元格内 sparkline 微型图表（线、列、胜/负）。 |
### 格式 / 视图
| 工具 | 操作 | 描述 |
|------|---------|-------------|
| `excel_format` | font, fill, border, number_format, alignment, column_width, row_height, autofit | 应用单元格格式：字体、填充、边框、数字格式、对齐、列/行大小、自适应。 |
| `excel_view` | freeze_panes, unfreeze_panes, gridlines, zoom, headings | 控制工作表显示设置：冻结窗格、网格线、缩放、行/列标题。 |
| `excel_conditional_format` | data_bar, color_scale, icon_set, cell_rule, top_bottom, clear | 添加或删除条件格式规则：数据条形图、颜色刻度、图标集、单元格规则、顶部/底部、清除。 |
| `excel_validation` | list, whole_number, decimal, date, text_length, custom, clear | 添加或删除范围的数据验证：下拉列表、数字/小数/日期/文本长度/自定义约束、清除。 |
### 页面 / 打印
| 工具 | 操作 | 描述 |
|------|---------|-------------|
| `excel_page_setup` | set, print_area, print_titles, header_footer, export_pdf, get | 配置页面设置并导出为 PDF：方向、纸张大小、边距、适应页面、打印区域、标题、页眉/页脚、PDF 导出。 |
### 注释
| 工具 | 操作 | 描述 |
|------|---------|-------------|
| `excel_comment` | add, edit, reply, delete, list, get | 添加、编辑、回复、删除、列表和获取单元格注释（旧版笔记和线程）。 |
| `excel_hyperlink` | add, list, delete | 添加、列表和删除工作表超链接（URL、内部、电子邮件、文件）。 |
| `excel_outline` | group_rows, group_columns, ungroup_rows, ungroup_columns, show_levels, clear | 分组/取消分组行和列，控制轮廓级别，清除所有分组。 |
| `excel_protection` | protect_sheet, unprotect_sheet, protect_workbook, unprotect_workbook, set_locked, status | 保护/取消保护工作表和工作簿，设置单元格锁定/公式隐藏标志，并查询保护状态。 |
### 安全
| 工具 | 操作 | 描述 |
|------|---------|-------------|
| `excel_vba` | list_modules, get_module, write_module, delete_module, run | 管理 VBA 模块并运行宏（可选，需要 `THEPEXCEL_MCP_ENABLE_VBA=1` 和 AccessVBOM 信任）。 |
| `excel_screenshot` | range, sheet, chart | 将范围、工作表或图表捕获为 PNG 以供 AI 代理进行视觉验证。 |
| `excel_find_replace` | find, count, replace | 在范围内、表格或整个工作簿中查找、计数或替换文本，支持大小写匹配和整单元格选项。 |
| `excel_diff` | ranges, sheets | 对比两个范围或两个完整表格的单元格级别差异，支持值、公式或两者（纯读取，无修改）。 |
| `excel_snapshot` | snapshot, list, restore, delete | 非破坏性工作簿安全副本：快照（SaveCopyAs）、列表、恢复（打开副本作为新工作簿）、删除。 |
## 环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
| `THEPEXCEL_MCP_AUTOLAUNCH` | 未设置 | 设置为 `1` 以自动启动一个可见的 Excel 实例（如果没有运行）。 |
| `THEPEXCEL_MCP_ENABLE_VBA` | 未设置 | 设置为 `1` 以启用 `excel_vba` 工具。默认为安全关闭。 |
| `THEPEXCEL_MCP_COM_TIMEOUT` | `120` | 每次调用的 COM 超时（秒）。增加超时时间以适应缓慢的数据刷新。 |
## VBA 设置
`excel_vba` 需要两个条件都打开：
1. 在注册服务器时设置环境变量 `THEPEXCEL_MCP_ENABLE_VBA=1`。
2. 在 Excel 中启用信任设置：**文件 → 选项 → 信任中心 → 信任中心设置 → 宏设置 → 勾选“信任访问 VBA 项目对象模型”**。
如果缺少两个条件之一，任何 `excel_vba` 调用都会返回一个明确的错误，说明缺少哪个条件。
## 使用捆绑的技能
仓库中包含一个 Claude 技能，位于 `skills/excel-god/` - 一个策略和协调指南，帮助 AI 代理为常见 Excel 任务（构建仪表板、清理 Power Query 数据、设置数据模型等）决定调用哪些工具以及调用顺序。
要使用它，请将 `excel-god` 文件夹复制到您的技能目录：
```bash
# 项目级
cp -r skills/excel-god /path/to/your/project/.claude/skills/
# 用户级（所有项目都可用）
cp -r skills/excel-god ~/.claude/skills/
```
然后在 Claude Code 会话中使用 `/excel-god` 调用它。
## 故障排除 / 已知限制
**Excel 必须在第一个调用前运行。**
服务器连接到 Windows 运行对象表中可见的第一个 Excel 实例。如果 Excel 未打开，所有工具调用都将失败并出现 COM 错误。或者，可以手动打开 Excel 或设置 `THEPEXCEL_MCP_AUTOLAUNCH=1`。
**截图和图表图像导出需要可见的 Excel 窗口。**
`excel_screenshot` 和 `excel_chart(export_image)` 使用 Excel 的 `CopyPicture` API，需要窗口在屏幕上渲染。如果 Excel 最小化或窗口被其他应用程序隐藏，捕获的 PNG 可能会为空。保持 Excel 窗口在这些工具运行时可见。
**数据模型 `add_table` 和 Power Query `load_to_datamodel` 在无界面 stdio 上下文中可能死锁。**
将数据加载到内存中的数据模型会触发 Mashup/Power Query 刷新，这需要 Excel 的 UI 消息泵。在 Claude Code CLI 会话（stdio 传输，无可见窗口）中，此操作可能会使 COM 工作线程死锁，并阻止所有后续工具调用，直到 Excel 被强制关闭。Claude Desktop 和完全可见的 Excel 窗口下运行正常。备用方案：使用 `excel_powerquery(load_to_table)` 将数据加载到工作表表格中，然后使用 `excel_pivot(create, source="<table name>")`（确切的流程 - 跨文件 Power Query 合并 → 表格 → 数据透视 → 图表 → 切片器 - 均已验证）。
**命名 LAMBDA 通过 `excel_name`。**
LAMBDA 中的参数名称不应类似单元格引用。避免使用 `q1`、`x2`、`c3` 等名称 - 使用描述性名称，如 `val`、`rate`、`n` 或 `x`。如果 LAMBDA 添加失败，Excel 可能会在工作簿中留下隐藏的 `_xlpm.*` 帮助名称，这些名称会阻止后续 LAMBDA 添加。如果发生这种情况，请使用新的工作簿。
**`=PY()` Excel 中的 Python。**
`excel_range(write_py)` 插入 Excel 中的 Python 代码，但执行由 Microsoft 的云服务异步处理。它需要 M365 Python in Excel 订阅和活动互联网连接。工具插入公式；它不等待或验证云结果。
**VBA `run` 返回值。**
`excel_vba(run)` 从 VBA 函数返回标量值（Long、String、Double）。Sub 过程返回 None。复杂返回类型（数组、对象）不受支持。
**Windows 专用。**
COM 是 Windows 技术。该服务器无法在 macOS 或 Linux 上运行。
## 开发
```bash
uv sync # 安装依赖
uv run pytest -q # 927 个单元测试，无需 Excel
THEPEXCEL_MCP_AUTOLAUNCH=1 uv run python tests/smoke_com.py # 实时 COM 冒烟测试（需要 Windows + Excel）
```
要运行子集的冒烟测试：
```bash
THEPEXCEL_MCP_AUTOLAUNCH=1 uv run python tests/smoke_com.py --sections 1,2,3,4
```
第 1-28 节涵盖所有工具类别。完整的套件大约需要 5-10 分钟，具体取决于 Excel 启动时间。
## 致谢
本项目建立在 Excel 自动化和 MCP 社区其他人的工作基础上：
- **[sbroenne/mcp-server-excel](https://github.com/sbroenne/mcp-server-excel)** （MIT）- 主要参考实现。许多 Excel COM 自动化序列在此从 C# 项目移植到 Python。如果您想要成熟的基于 C#/.NET COM 的 Excel MCP 服务器，他们的服务器非常优秀。
- **[lingfan36/ai-office-mcp](https://github.com/lingfan36/ai-office-mcp)** - 工具设计的灵感来源。
- **[haris-musa/excel-mcp-server](https://github.com/haris-musa/excel-mcp-server)** - MCP 工具 API 设计惯例的参考。
上游许可文本在 [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md) 中复制。
## 贡献
在分支上工作并打开拉取请求 - `main` 被保护。请使用合成数据（此仓库是公共仓库），并启用推送前的安全钩子。有关详细信息，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
MIT 许可证。版权所有 (c) 2026 ThepExcel <thepexcel@gmail.com>。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器