Google Sheet Analytics MCP

🚀 TNTM Google表格分析MCP服務器

TNTM打造的一款簡潔實用的MCP（模型上下文協議）服務器，支持多標籤，可用於分析Google表格數據。該服務器專為Claude Desktop及其他兼容MCP的AI助手而設計。

🚀 快速開始

TNTM Google表格分析MCP服務器是一款強大的工具，用於分析Google表格數據。以下是使用該服務器的基本步驟：

1. 確保滿足所有先決條件。
2. 按照設置步驟進行安裝和配置。
3. 重啟MCP客戶端（如Claude Desktop），首次使用工具時將自動啟動OAuth流程。

✨ 主要特性

• 智能同步：同步Google表格時可配置行限制，防止超時。
• 多標籤支持：可使用SQL JOIN跨多個工作表進行查詢。
• SQL查詢：可直接對同步的數據進行SQL查詢。
• 表格分析：提供跨工作表查詢的建議。
• 快速預覽：無需完全同步即可預覽工作表。
• 性能優化：針對大型數據集設置行限制和結果分頁。

📦 安裝指南

1. 克隆並安裝

git clone https://github.com/yourusername/google-sheet-analytics-mcp.git
cd google-sheet-analytics-mcp
python3 -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate
pip install -r requirements.txt

2. Google Cloud設置

1. 訪問 Google Cloud控制檯。
2. 創建一個新項目或選擇現有項目。
3. 啟用Google表格API。
4. 創建OAuth2憑據（桌面應用程序）。
5. 下載憑據並保存為項目根目錄下的 credentials.json。

3. 運行自動設置

python3 setup.py

這將：

• 設置OAuth身份驗證。
• 自動配置Claude Desktop。
• 測試連接。

或者手動配置MCP客戶端：

{
  "mcpServers": {
    "google-sheets-analytics": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["/path/to/google-sheet-analytics-mcp/src/mcp_server.py"]
    }
  }
}

4. 首次運行

重啟MCP客戶端（如Claude Desktop），首次使用工具時將自動啟動OAuth流程。

💻 使用示例

基礎用法

多標籤分析

-- 結合銷售數據和客戶信息
SELECT 
  s.product_name, 
  s.sales_amount, 
  c.customer_name, 
  c.customer_segment
FROM sales_data s 
JOIN customer_data c ON s.customer_id = c.id
WHERE s.sales_amount > 1000

跨工作表聚合

-- 從多個工作表按地區統計總收入
SELECT 
  region, 
  SUM(amount) as total_revenue
FROM (
  SELECT region, amount FROM q1_sales
  UNION ALL
  SELECT region, amount FROM q2_sales
)
GROUP BY region
ORDER BY total_revenue DESC

高級用法

smart_sync

同步Google表格數據並進行性能控制。

使用 smart_sync，指定URL "https://docs.google.com/spreadsheets/d/your_sheet_id" 並設置最大行數為 500

• url（必需）：Google表格URL
• max_rows（可選）：每個工作表的最大行數（默認：1000）
• sheets（可選）：要同步的特定工作表名稱數組

query_sheets

對同步的數據運行SQL查詢，包括跨標籤的JOIN操作。

使用 query_sheets 執行查詢 "SELECT * FROM sheet1 JOIN sheet2 ON sheet1.id = sheet2.id LIMIT 10"

• query（必需）：要執行的SQL查詢

list_synced_sheets

查看所有已同步的工作表及其表名。

使用 list_synced_sheets

analyze_sheets

獲取跨多個工作表的查詢建議。

使用 analyze_sheets 並提出問題 "如何將銷售數據與客戶數據結合起來？"

• question（必需）：要分析的問題

get_sheet_preview

無需同步即可快速預覽。

使用 get_sheet_preview，指定URL "https://docs.google.com/spreadsheets/d/your_sheet_id" 並設置預覽行數為 20

• url（必需）：Google表格URL
• sheet_name（可選）：要預覽的特定工作表
• rows（可選）：要預覽的行數（默認：10）

📚 詳細文檔

📊 工作原理

1. 身份驗證：使用OAuth2安全訪問Google表格API。
2. 同步：將表格數據下載到本地SQLite數據庫，並可配置限制。
3. 查詢：支持對所有已同步的工作表進行SQL查詢。
4. 多標籤：每個工作表成為一個單獨的表，可通過SQL進行連接。

🏗️ 項目結構

google-sheet-analytics-mcp/
├── src/
│   ├── mcp_server.py          # 主MCP服務器實現
│   └── auth/
│       └── oauth_setup.py     # 統一的OAuth身份驗證模塊
├── setup.py                   # 統一的設置腳本（處理所有事情）
├── requirements.txt           # Python依賴項
├── credentials.json.example   # 示例OAuth憑據格式
├── README.md                  # 本文件
├── LICENSE                    # MIT許可證
├── CLAUDE.md                  # Claude特定說明
├── data/                      # 運行時數據（自動創建）
│   ├── token.json            # OAuth令牌（設置期間創建）
│   └── sheets_data.sqlite    # 本地數據庫（首次同步時創建）
└── venv/                      # 虛擬環境（設置期間創建）

⚡ 性能

• 行限制：每個工作表默認1000行（可配置）。
• 結果限制：查詢結果限制為100行。
• 本地存儲：使用SQLite數據庫進行快速重複查詢。
• 元數據跟蹤：高效重新同步更改的數據。
• 內存高效：採用流式數據處理。

🔍 示例用例

上述使用示例部分已提供了多標籤分析和跨工作表聚合的示例。

🔧 技術細節

身份驗證

使用OAuth2協議確保安全訪問Google表格API。通過 src/auth/oauth_setup.py 模塊進行統一的OAuth身份驗證設置。

數據同步

將Google表格數據下載到本地SQLite數據庫，可通過配置行限制來控制同步的數據量。在首次同步時會創建 data/sheets_data.sqlite 數據庫文件。

SQL查詢

支持對同步到本地數據庫的所有工作表進行SQL查詢，包括跨標籤的JOIN操作。每個工作表在數據庫中作為一個單獨的表存在。

性能優化

通過設置行限制、結果限制、本地存儲、元數據跟蹤和流式數據處理等方式，確保服務器在處理大型數據集時具有良好的性能。

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE 文件。

🙏 致謝

• 為 模型上下文協議 而構建。
• 專為 Claude Desktop 設計。
• 使用 Google表格API。

需要幫助？ 在GitHub上創建一個問題或查看上述故障排除部分。

🐛 故障排除

常見問題

OAuth故障排除

• 檢查狀態：venv/bin/python src/auth/oauth_setup.py --status
• 測試身份驗證：venv/bin/python src/auth/oauth_setup.py --test
• 重置OAuth：venv/bin/python src/auth/oauth_setup.py --reset
• 手動設置：venv/bin/python src/auth/oauth_setup.py --manual

MCP服務器未顯示

1. 確保Claude Desktop已完全關閉。
2. 驗證配置：cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
3. 檢查配置中是否包含google-sheets-analytics服務器。
4. 重啟Claude Desktop。
5. 檢查開發者控制檯是否有錯誤信息。

數據庫問題

• 數據庫位置：data/sheets_data.sqlite
• 重置數據庫：刪除該文件並重新同步。
• 檢查已同步的工作表：使用 list_synced_sheets 工具。

🤝 貢獻

1. 分叉倉庫。
2. 創建一個功能分支 (git checkout -b feature/amazing-feature)。
3. 提交更改 (git commit -m '添加驚人的功能')。
4. 推送到該分支 (git push origin feature/amazing-feature)。
5. 打開一個拉取請求。