Spreadsheet MCP Server

Spreadsheet MCP Server

本项目是一个用于访问 Google Spreadsheet 数据的 Model Context Protocol（MCP）服务，可让大模型直接使用电子表格信息。

功能

• 获取电子表格的基本信息（例如工作表列表）
• 获取特定工作表的数据，并将其整理为 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 App 端实现访问电子表格的 API（参见 api/README.md）
3. 设置 API 密钥，并通过环境变量 GAS_WEB_APP_URL 和 GAS_API_KEY 进行连接

通过这种方式，可以绕过 Google 身份验证流程，同时保障电子表格的安全性。

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

许可证

MIT