google-gsc

mcp-google-gsc

Google Search Console 用 MCP サーバーです。Claude を通じて検索アナリティクス、URL 検査、サイト管理を行えます。

機能

• 検索アナリティクス -- ディメンションフィルター（クエリ、ページ、デバイス、国、日付）を柔軟に指定して、クリック数、表示回数、CTR、掲載順位を照会します
• URL 検査 -- あらゆる URL のインデックス登録状況、モバイルユーザビリティ、リッチリザルトを確認します
• サイト一覧 -- 認証済みアカウント（OAuth ユーザーまたはサービスアカウント）からアクセスできる、確認済みの Search Console プロパティをすべて一覧表示します
• 複数クライアントのサポート -- ディレクトリごとの設定マッピングを使用して、複数の GSC プロパティを管理します

インストール

npm から

npm install mcp-google-gsc

ソースから

git clone https://github.com/mharnett/mcp-search-console.git
cd mcp-google-gsc
npm install
npm run build

設定

セキュリティ： .mcp.json ファイルを共有したり、Git にコミットしたりしないでください。API 認証情報が含まれている可能性があります。.mcp.json を .gitignore に追加してください。

mcp-gsc は2 つの認証モードに対応しています。環境に合った方を選んでください。どちらのモードも、固定されたマシンローカルパスにファイルを置く必要はありません。認証情報は環境変数（または作成した config.json）から取得されます。

使用するモード：

• サービスアカウント（モード B） -- 無人運用／サーバー／ヘッドレス環境に推奨。 サービスアカウントは、期限切れになったり再同意が必要になったりするインタラクティブなログインを伴わないため、常時稼働のデプロイに適しています。設定に必要なのは、照会する各 Search Console プロパティでサービスアカウントのメールアドレスにアクセス権を付与することだけです（モード B を参照）。
• ユーザー OAuth（モード A） -- 個人利用／インタラクティブな利用向けです。自身の Google アカウントで認証したい場合に使用します。

両方を設定した場合の優先順位： サービスアカウントのキーファイルが明示的に設定されている場合（GOOGLE_APPLICATION_CREDENTIALS、または config.json の credentials_file）、OAuth リフレッシュトークンや保存済みの OAuth 認証情報よりも優先されます。どちらも設定されていない場合、サーバーは推測して処理を続けるのではなく、オンボーディングメッセージを表示して起動時に明確なエラーで終了します。マシンローカルのデフォルトも、2 つのモード間でのサイレントな実行時フォールバックもありません。

モード A：ユーザー OAuth（自身の Google アカウントを使用）

自身の Google アカウント（Search Console にアクセスできるアカウント）で認証する場合に使用します。個人利用／インタラクティブな利用に最適です。

1. Google Cloud Console で、種類がデスクトップアプリの OAuth 2.0 クライアント ID を作成し、Search Console API を有効にします。（デスクトップアプリのクライアントでは、Google は任意の http://localhost ループバックリダイレクトを受け付けます。ポートを事前登録する必要はありません。）
2. クライアント認証情報をエクスポートします：

   export GOOGLE_GSC_CLIENT_ID=...apps.googleusercontent.com
   export GOOGLE_GSC_CLIENT_SECRET=...
   

3. リフレッシュトークンを取得します（ブラウザーが開き、PKCE と access_type=offline を使用します）：

   node get-refresh-token.cjs
   

   このコマンドの標準出力を共有ログにリダイレクトしないでください。設計上、リフレッシュトークンが標準出力に出力されます。

4. 出力された行を環境にコピーします：

   export GOOGLE_GSC_REFRESH_TOKEN=...
   

サーバーは実行時に、環境から GOOGLE_GSC_CLIENT_ID、GOOGLE_GSC_CLIENT_SECRET、GOOGLE_GSC_REFRESH_TOKEN を読み取ります。

または、ガイド付きヘルパー npx mcp-gsc-auth を実行できます。同じ PKCE OAuth フローを実行し、デフォルトの Search Console プロパティを選択できるほか、結果をユーザーごとの認証情報ファイルに書き込みます。

モード B：サービスアカウント（無人運用／サーバー利用に推奨）

サーバー／ヘッドレス／常時稼働の環境で使用します。インタラクティブなログインを完了または更新する人がいない場合に推奨される方法です。

1. Search Console API へのアクセス権を持つ Google Cloud サービスアカウントを作成し、その JSON キーファイルをダウンロードします。
2. 照会する各 Search Console プロパティで、サービスアカウントのメールアドレスにアクセス権を付与します（Search Console でユーザーとして追加します）。プロパティへのアクセス権が付与されていない場合、サービスアカウントは認証されてもサイトを参照できません。
3. 環境変数を使用してキーファイルをサーバーに指定します（固定パスは使用しません）：

   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json
   

OAuth スコープ

どちらのモードも、単一の読み取り専用スコープ https://www.googleapis.com/auth/webmasters.readonly を要求します。4 つのツールはいずれも読み取り専用で、書き込みは行わないため、サーバーが読み書きアクセスを要求することはありません。

スコープは config.json の oauth.scope で一度だけ定義します（config.example.json を参照）。OAuth ヘルパーとランタイムは同じ値を読み取るため、値が食い違うことはありません。config.json が存在しない場合（新規インストール時など）は、コミット済みの読み取り専用のデフォルト値が使用されます。

複数クライアントの設定（任意）

作業ディレクトリと Search Console プロパティを対応付けるには、プロジェクトのルートに config.json を作成します（config.example.json を参照）。

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/webmasters.readonly"
  },
  "clients": {
    "my-project": {
      "name": "My Project",
      "folder": "/path/to/project",
      "site_url": "https://example.com/"
    }
  }
}

使用方法

Claude Code の .mcp.json に追加します。

{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/path/to/mcp-gsc/dist/index.js"]
    }
  }
}

グローバルにインストールした場合：

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["mcp-google-gsc"]
    }
  }
}

Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。

ツール

ツール	説明
gsc_get_client_context	設定の対応付けに基づいて、作業ディレクトリから GSC プロパティを検出します
gsc_list_sites	認証済みアカウントからアクセス可能な、確認済みの Search Console プロパティをすべて一覧表示します
gsc_search_analytics	ディメンションとフィルターに対応し、検索パフォーマンスデータ（クリック数、表示回数、CTR、掲載順位）を照会します
gsc_inspection	URL のインデックス登録状況、モバイル ユーザビリティ、リッチリザルトを検査します

gsc_search_analytics

対応するディメンションは query、page、device、country、date です。equals、contains、notContains などの演算子を使って、任意のディメンションでフィルターできます。日付範囲のデフォルトは過去 28 日間です。

gsc_inspection

プロパティ内の特定の URL について、インデックス カバレッジ、クロール状況、モバイル ユーザビリティの判定、リッチリザルトの詳細を返します。

アーキテクチャ

• レジリエンス -- cockatiel を使用し、すべての Google API 呼び出しに指数バックオフによる再試行とサーキットブレーカーのパターンを適用します
• ロギング -- pino による構造化ロギングを採用し、ログレベルを設定できます
• レスポンス処理 -- MCP のトランスポート制限内に収めるため、レスポンスを 200KB で切り詰めます

ライセンス

MIT -- LICENSE を参照してください。

---

Mark Harnett / drak-marketing によって作成されました