ga-gsc-analytics

読み取り専用のMCPサーバーで、Google Analytics 4 と Google Search Console のデータ（analytics.readonly + webmasters.readonly スコープ）を Claude Code / Codex に公開します。

初めての方へ？ ONBOARDING.md に従って、ゼロから動作するまでの手順（Claude Code のインストール、認証情報の取得、認可、確認）を進めてください。このファイルの残りは参考資料です。

AIエージェント向け: このファイルは AGENTS.md を兼ねています。セットアップはここから始め、ツールの使い方（アクセスチェック、デフォルトの日付範囲、GA4 と GSC の意味論、プレゼンテーション引き継ぎ形式）については skills/analyze-ga-gsc/SKILL.md を読んでください。ユーザーにチャットで認証情報を貼り付けさせないでください。

ツール

• analytics_auth_start / analytics_auth_status — ローカルOAuthフローとステータス確認

• analytics_list_sources — 認可されたアカウントで利用可能な GA4 プロパティと GSC サイトを一覧表示

• ga_run_report — GA4 レポートを実行

• gsc_query_search_analytics — Search Console データを照会

• analytics_presentation_snapshot — レポート用の GA4 + GSC の複合スナップショット

Related MCP server: BigQuery MCP Server

セットアップ（ユーザーごと）

各ユーザーは自分の Google アカウントで認可し、自分のローカルトークンを保持します。client_secret.json のシークレットや tokens.json をマシン間で共有しないでください。

1. Google Cloud OAuth クライアント: Google Cloud Console で OAuth 2.0 デスクトップクライアントを作成（または既存を再利用）し、その client_secret.json をダウンロードします。同意画面が「テスト中」の公開ステータスの場合、先に各新規ユーザーの Google アカウントをテストユーザーとして追加しないと、認可がアクセス拒否で失敗します。

2. 認証情報を配置: ~/.config/ga-gsc-analytics/client_secret.json に配置します（または GA_GSC_CLIENT_SECRET でカスタムパスを指定）。

3. データアクセスを付与: 認可する Google アカウントには、対象の GA4 プロパティ（Analytics Admin → プロパティのアクセス管理）と GSC サイト（Search Console → 設定 → ユーザーと権限）に対する実際の権限が必要です。

4. サーバーをビルド（mcp/server.mjs を変更した場合のみ必要。リポジトリにはビルド済みの mcp/server.bundle.cjs が同梱されています）:

pnpm install
pnpm run build   # bundles mcp/server.mjs -> mcp/server.bundle.cjs

5. MCP サーバーを登録。次のいずれかで行います:

   • Claude Code、ユーザーレベル: claude mcp add ga-gsc-analytics -- node /path/to/ga-gsc-analytics/mcp/server.bundle.cjs

   • Claude Code / Codex、プロジェクトスコープ: このリポジトリには相対パスの .mcp.json（{"mcpServers": {"ga_gsc_analytics": {"command": "node", "args": ["./mcp/server.bundle.cjs"]}}}）が同梱されています。これをプロジェクトにコピーするか、このフォルダ全体をシンボリックリンクまたはベンダーとして取り込むと、そのプロジェクトを開いたときに自動的に認識されます。

6. 認可: AI ツール内から analytics_auth_start ツールを呼び出します。ローカルブラウザの OAuth フローが開き、~/.config/ga-gsc-analytics/tokens.json に書き込まれます。

7. 確認: analytics_auth_status を呼び出し（authorized: true と表示されるはず）、次に analytics_list_sources を呼び出して、期待する GA4 プロパティ / GSC サイトが表示されることを確認します。

設定の上書き

開発

pnpm run check   # syntax check
pnpm test        # node --test tests/*.test.mjs