Google Sheet Analytics MCP

🚀 TNTM Google Sheets Analytics MCP Server

TNTMによってClaude Desktopやその他のMCP互換AIアシスタント向けに構築された、複数タブをサポートするGoogle Sheetsデータ分析用の、クリーンで実用的なMCP（Model Context Protocol）サーバーです。

🚀 クイックスタート

このサーバーは、Google Sheetsのデータ分析を支援するためのMCPサーバーです。以下の手順に従ってセットアップしてください。

✨ 主な機能

• スマート同期 - タイムアウトを防ぐために、設定可能な行制限でGoogle Sheetsを同期します。
• 複数タブサポート - 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  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Google Cloudの設定

1. Google Cloud Consoleにアクセスします。
2. 新しいプロジェクトを作成するか、既存のプロジェクトを選択します。
3. Google Sheets 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フローが自動的に開始されます。

💻 使用例

基本的な使用法

smart_sync

Use smart_sync with url "https://docs.google.com/spreadsheets/d/your_sheet_id" and max_rows 500

• url (必須): Google SheetsのURL
• max_rows (オプション): シートごとの最大行数（デフォルト: 1000）
• sheets (オプション): 同期する特定のシート名の配列

query_sheets

Use query_sheets with query "SELECT * FROM sheet1 JOIN sheet2 ON sheet1.id = sheet2.id LIMIT 10"

• query (必須): 実行するSQLクエリ

list_synced_sheets

Use list_synced_sheets

analyze_sheets

Use analyze_sheets with question "How can I combine sales data with customer data?"

• question (必須): 分析したい内容

get_sheet_preview

Use get_sheet_preview with url "https://docs.google.com/spreadsheets/d/your_sheet_id" and rows 20

• url (必須): Google SheetsのURL
• sheet_name (オプション): プレビューする特定のシート
• rows (オプション): プレビューする行数（デフォルト: 10）

高度な使用法

複数タブ分析

-- Combine sales data with customer information
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

複数シートの集計

-- Total revenue by region from multiple sheets
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

📚 ドキュメント

仕組み

1. 認証 - OAuth2を使用してGoogle Sheets APIに安全にアクセスします。
2. 同期 - 設定可能な制限でシートデータをローカルのSQLiteデータベースにダウンロードします。
3. クエリ - すべての同期されたシートに対してSQLクエリを実行できます。
4. 複数タブ - 各シートは別のテーブルとなり、SQLを介して結合できます。

プロジェクト構造

google-sheet-analytics-mcp/
├── src/
│   ├── mcp_server.py          # Main MCP server implementation
│   └── auth/
│       └── oauth_setup.py     # Unified OAuth authentication module
├── setup.py                   # Unified setup script (handles everything)
├── requirements.txt           # Python dependencies
├── credentials.json.example   # Example OAuth credentials format
├── README.md                  # This file
├── LICENSE                    # MIT License
├── CLAUDE.md                  # Claude-specific instructions
├── data/                      # Runtime data (created automatically)
│   ├── token.json            # OAuth token (created during setup)
│   └── sheets_data.sqlite    # Local database (created on first sync)
└── venv/                      # Virtual environment (created during setup)

パフォーマンス

• 行制限: シートごとのデフォルト行数は1000行（設定可能）
• 結果制限: クエリ結果は100行に制限されます。
• ローカルストレージ: 高速な繰り返しクエリのためにSQLiteデータベースを使用します。
• メタデータ追跡: 変更されたデータの効率的な再同期をサポートします。
• メモリ効率: ストリーミングデータ処理を行います。

🔧 技術詳細

このサーバーは、Pythonで構築されており、Google Sheets APIを使用してデータを取得し、SQLiteデータベースに保存します。OAuth2認証を使用して安全にアクセスし、SQLクエリを介してデータを操作できます。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

🙏 謝辞

• Model Context Protocol向けに構築されました。
• Claude Desktop用に設計されました。
• Google Sheets APIを使用しています。

ヘルプが必要ですか？ GitHubでイシューを開くか、上記のトラブルシューティングセクションを確認してください。