<!-- 对应 docs/03-detailed-design.md 第 4.1 节：触点一 npm 包说明页 -->

# mcp-excel —— 让 AI 助手直接读写你电脑上的 Excel 文件

<p align="center">
  <a href="https://www.npmjs.com/package/mcp-excel"><img src="https://img.shields.io/npm/v/mcp-excel" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/mcp-excel"><img src="https://img.shields.io/npm/dm/mcp-excel" alt="npm downloads"></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="node version"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/npm/l/mcp-excel" alt="license"></a>
</p>

支持 `.xlsx` / `.xls` / `.csv` 格式。

<!-- 第 4.1 节第 2 点：它能干什么 -->
## 它能干什么

- 读取本地 Excel / CSV 文件，让 AI 直接回答表格内容相关的问题。
- 新建 `.xlsx` 文件，并创建多张初始工作表。
- 修改单元格、批量写入二维数组、设置 Excel 公式。
- 设置字体、填充色、边框、对齐、数字格式，合并单元格、调整列宽行高美化表格。
- 对工作表区域排序、筛选、去重。
- 把本地 `png / jpg / gif` 图片插入到工作表指定位置。

<!-- 第 4.1 节第 3 点：安装与配置。配置示例必须原样可用 -->
## 安装与配置

需要 Node.js 20 或以上。在 AI 助手的 MCP 配置中加入：

```json
{
  "mcpServers": {
    "excel": {
      "command": "npx",
      "args": ["-y", "mcp-excel"]
    }
  }
}
```

保存配置后，重启 AI 助手即可生效。

<!-- 第 4.1 节第 4 点：使用示例 -->
## 使用示例

- 帮我看看 `D:\报表\2026年销售记录.xlsx` 里“一月”那张表，总销售额是多少？
- 新建一个 Excel，12 张 Sheet，每张是一个月考勤表，第一行写姓名和 1 到 31 号。
- 把“费用表” B5 的 3000 改成 3500，最后加一行合计。

<!-- 第 4.1 节第 5 点：支持的格式与限制。如实写明，防止错误预期 -->
## 支持的格式与限制

- `.xlsx`：全功能支持。
- `.xls`：仅支持读取；如需修改，请先在 Excel / WPS 中另存为 `.xlsx`。
- `.csv`：支持读写单元格值，但仅有一张工作表，不支持样式、合并单元格、图片等。
- 修改含有图表、数据透视表、宏（如 `.xlsm` 中的 VBA）的文件时，这些元素可能在保存过程中丢失。
- 本工具写入的公式不带缓存计算结果，需要在 Excel / WPS 中打开一次后才会显示计算值。

<!-- 第 4.1 节第 6 点：隐私说明 -->
## 隐私说明

所有处理都在你自己的电脑上完成，不上传任何数据。

<!-- 第 4.1 节第 7 点：License -->
## License

MIT