Hosakakeigo Spreadsheet MCP Server

🚀 Google 表格 MCP 服務器

本項目是一個基於 Model Context Protocol (MCP) 的服務器，專門用於訪問 Google 表格數據。它為大語言模型（LLM）提供了直接使用表格信息的能力，極大地提升了數據交互的便捷性。

🚀 快速開始

此項目是一個用於訪問 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 身份驗證的情況下，安全地使用表格數據。如果未配置環境變量，服務器將以模擬模式運行，並返回測試數據。