Hosakakeigo Spreadsheet MCP Server

🚀 Google 表格 MCP 服务器

本项目是一个基于 Model Context Protocol (MCP) 的服务器，专门用于访问 Google 表格数据。它为大语言模型（LLM）提供了直接使用表格信息的便捷途径，极大地提升了数据交互的效率。

✨ 主要特性

• 获取表格基本信息：可轻松获取表格的基本信息，例如工作表列表等。
• 整理工作表数据：能够获取特定工作表的数据，并将其整理为 Markdown 格式，方便查看和使用。
• 集成 MCP 客户端：可以与 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 身份验证的情况下，安全地使用表格数据。如果未配置环境变量，服务器将以模拟模式运行，并返回测试数据。