Google 表格 MCP 服务器

此项目是一个用于访问 Google 表格数据的 Model Context Protocol (MCP) 服务器。它使 LLM 直接能够使用表格信息。

功能

• 获取表格的基本信息（如工作表列表等）
• 获取特定工作表的数据，并以 Markdown 格式进行整理
• 与 MCP 客户端（如 Desktop 版 Claude 等）集成

安装

# 克隆仓库
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 脚本 Web 应用的 URL
• GAS_API_KEY: 访问 Google Apps 脚本 Web 应用的 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

与 Desktop 版 Claude 集成

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

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["<绝对路径到项目>/build/index.js"]
    }
  }
}

要设置环境变量，请在配置文件中添加 env 字段如下：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "node",
      "args": ["<绝对路径到项目>/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 Server 的使用

要访问表格数据，可以在代码中调用 MCP 服务：

import { createMCPClient } from 'mcp-client'

const mcp = await createMCPClient('spreadsheet')
await mcp.query('获取表格内容', {
  spreadsheetId: '<表格 ID>',
  sheetName: '<工作表名称>'
})

开发信息

项目结构

项目文件夹结构如下：

src/
  |- api/                   # 定义与 Web 应用交互的接口
  |- mock/                 # 模拟数据（未配置环境变量时使用）
  |- services/             # 处理表格数据的核心逻辑
    |- SpreadsheetService.ts   # 表格数据处理类

开发步骤

1. 安装依赖：

npm install

2. 启动开发服务器：

npm run dev

测试说明

要运行测试：

npm test

集成 Google Apps Script Web 应用

要使用 Google 表格数据，请按照以下步骤操作：

1. 创建 Google Apps 脚本 Web 应用：创建指南

2. 在 Web 应用中实现访问表格的 API（参考 api/README.md）

3. 配置环境变量 GAS_WEB_APP_URL 和 GAS_API_KEY

通过此方法，可以在不经过 Google 身份验证的情况下，安全地使用表格数据。

如果未配置环境变量，服务器将以模拟模式运行，并返回测试数据。