Spreadsheet MCP

🚀 电子表格 MCP 服务器 (@zephyr-mcp/spreadsheet)

这是一个基于 TypeScript 的模型上下文协议 (MCP) 服务器，借助 LLM 或 API 集成，可对 CSV/XLSX 电子表格文件进行查看、筛选、排序和更新等操作，为电子表格处理提供便利。

🚀 快速开始

此包设计为直接使用 npx 运行，典型用法无需安装。不过，需要满足以下先决条件：

• Node.js v18+ (推荐 LTS 版本)

在 stdio 模式下启动服务器 (用于与 Cline 等工具集成)：

npx @zephyr-mcp/spreadsheet

服务器将启动并通过标准输入/输出监听 MCP 命令。

✨ 主要特性

• 查看电子表格信息并预览行
• 按列和条件筛选行
• 按列排序行 (升序/降序)
• 向现有 XLSX 文件添加新工作表或创建新文件
• 支持 CSV 和 XLSX 文件
• 以包含二维数组的 JSON 字符串形式返回结果 (用于查看/筛选/排序)
• 技术栈：TypeScript, fastmcp, papaparse, xlsx, zod

📦 安装指南

开发环境设置

若要进行开发，可按以下步骤操作：

1. 克隆仓库：

   git clone https://github.com/your-username/spreadsheet-mcp.git # 替换为你的仓库 URL
   cd spreadsheet-mcp
   

2. 安装依赖：

   npm install
   

启动开发服务器

npm run dev

💻 使用示例

示例工具

• view_spreadsheet：查看文件信息并预览指定行数。返回包含文件信息和预览数据（二维数组）的 JSON 字符串。rows 参数指定预览行数（0 表示仅表头，默认为 10，无最大限制）。
• filter_spreadsheet：按列和条件筛选行。返回包含筛选结果（二维数组）的 JSON 字符串。rows 参数指定返回的最大行数（默认为所有匹配行，无最大限制）。
• sort_spreadsheet：按列排序行。返回包含排序结果（二维数组）的 JSON 字符串。rows 参数指定返回的最大行数（默认为所有行，无最大限制）。
• update_spreadsheet_with_new_sheet：将数据写入 XLSX 文件的新工作表

📚 详细文档

测试

npm test

发布

1. 更新包版本：

   npm version major/minor/patch
   

2. 提交更改并推送到远程仓库。
3. 构建并发布：

   npm run build
   npm publish
   

🔧 技术细节

项目结构

- src/
  ├── server.ts            # MCP 服务器入口, 工具注册
  └── spreadsheetUtils.ts  # 电子表格解析、筛选、格式化、写入
- tests/
  └── server.test.ts

📄 许可证

MIT License © 2025 Zephyr

👨‍💻 作者

Zephyr