Spreadsheet MCP 服务器

本项目是一个用于访问 Google Spreadsheet 数据的 Model Context Protocol (MCP) 服务器。它允许 LLM 直接利用电子表格信息。

功能

• 获取电子表格的基本信息（例如工作表列表）
• 获取特定工作表的数据并以 Markdown 格式进行格式化
• 与 MCP 客户端（例如 Claude for Desktop）集成

安装

# 克隆仓库
git clone https://github.com/your-username/spreadsheet-mcp-server.git
cd spreadsheet-mcp-server

# 安装依赖
npm install

# 设置环境变量
cp .env.example .env
# 编辑 .env 文件并设置 GAS_WEB_APP_URL 和 GAS_API_KEY

# 构建
npm run build

环境变量设置

服务器配置使用以下环境变量：

• GAS_WEB_APP_URL: Google Apps Script Web App 的 URL
• GAS_API_KEY: Google Apps Script Web App 的访问 API 密钥

这些环境变量可以在 .env 文件中设置：

GAS_WEB_APP_URL=https://script.google.com/macros/s/your-deployment-id/exec
GAS_API_KEY=your-api-key

如果未设置环境变量，服务器将以模拟模式运行，并且不会访问实际的 Google 电子表格。

使用方法

独立启动

npm start

与 Claude for Desktop 集成

将以下内容添加到 Claude for Desktop 的配置文件 (claude_desktop_config.json) 中：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["<absolute-path-to-project>/build/index.js"]
    }
  }
}

要设置环境变量，请添加 env 字段，如下所示：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["<absolute-path-to-project>/build/index.js"],
      "env": {
        "GAS_WEB_APP_URL": "https://script.google.com/macros/s/your-deployment-id/exec",
        "GAS_API_KEY": "your-api-key"
      }
    }
  }
}

配置文件位于以下位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %AppData%\\Claude\\claude_desktop_config.json

使用 MCP Inspector 进行测试

npx @modelcontextprotocol/inspector node build/index.js

提供的工具

getSpreadsheet

获取电子表格的基本信息和包含的工作表列表。

输入参数:

• url: 电子表格的 URL

输出:

• 电子表格名称、ID 和工作表列表（包括行数和列数）

getSheetData

获取电子表格中特定工作表的数据。

输入参数:

• url: 电子表格的 URL
• sheetName: 要获取的工作表名称

输出:

• 工作表数据（Markdown 表格格式）

开发

项目结构

src/
├── index.ts           # 入口点
├── server.ts          # MCP 服务器配置
├── config.ts          # 环境变量和配置管理
├── tools/             # 工具实现
│   ├── getSpreadsheet.ts
│   ├── getSheetData.ts
│   └── index.ts
├── api/               # API 处理
│   ├── README.md      # API 规范
│   ├── spreadsheet.ts
│   └── types.ts
└── utils/             # 实用程序
    └── format.ts

测试

# 运行单元测试
npm test

# 在观察模式下进行测试
npm run test:watch

关于与 Google Apps Script 的集成

此服务器在实际使用时与 Google Apps Script Web App 协同工作：

1. 在 Google Apps Script 中创建一个 Web App
2. 在 Web 应用程序端实现一个访问电子表格的 API（请参阅 api/README.md）
3. 设置 API 密钥，并通过环境变量 GAS_WEB_APP_URL 和 GAS_API_KEY 进行集成

这种方法可以避免 Google 身份验证流程并保持电子表格的安全性。

如果未设置环境变量，则以模拟模式运行，并返回测试数据。

许可证

MIT