mcp-google-gsc

Google Search Console 用 MCP サーバー -- Claude 経由での検索アナリティクス、URL 検査、サイト管理。

機能

• 検索アナリティクス -- クリック数、インプレッション数、CTR、掲載順位を、柔軟なディメンションフィルター（クエリ、ページ、デバイス、国、日付）で照会

• URL 検査 -- 任意の URL のインデックスステータス、モバイルユーザビリティ、リッチリザルトを確認

• サイト一覧 -- 認証済みアカウント（OAuth ユーザーまたはサービスアカウント）からアクセスできる、確認済みの Search Console プロパティをすべて一覧表示

• マルチクライアント対応 -- ディレクトリごとの設定マッピングで複数の GSC プロパティを管理

Related MCP server: Google Search Console MCP Server

インストール

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 資格情報よりも 優先されます。どちらも設定されていない場合、サーバーは起動時にオンボーディングメッセージとともに明示的に失敗します -- マシンローカルのデフォルトはなく、モード間の暗黙のランタイムフェイルオーバーもありません。

モード 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_search_analytics

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

gsc_inspection

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

アーキテクチャ

• 耐障害性 -- すべての Google API 呼び出しで、指数バックオフとサーキットブレーカーパターンを備えたリトライに cockatiel を使用

• ロギング -- 設定可能なログレベルを持つ pino による構造化ロギング

• レスポンス処理 -- MCP トランスポートの制限内に収めるため、レスポンスは 200KB で切り詰められます

ライセンス

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

Mark Harnett / drak-marketing によって構築されました。