Google Custom Search MCP

Google Custom Search MCP

English | Русский

A1 Google Custom Search MCP を使うと、Programmable Search Engine を通じて、AI アプリから自然な言葉でウェブや画像を検索できます。ページの検索、言語・国・日付・サイトによる絞り込み、検索結果のページ送り、サムネイル付き画像ファイルの取得を依頼できます。

Google Cloud API キーを使って、Google Custom Search JSON API を利用します。検索対象は、ごく少数のサイトからウェブ全体まで、エンジン側で決定します。また、このサーバーは JSON API の制限を明示し、あらゆる検索タスクが可能であるかのように示すことはありません。

• ツールは3つです。 ウェブ検索、画像検索、そして型付きツールでは公開されていないパラメーターを指定するための、生の GET リクエスト用ツールです。
• 最初から最後まで読み取り専用です。 Custom Search JSON API には書き込み用のエンドポイントがありません。すべてのツールが読み取り専用としてマークされており、ここからデータを変更することはできません。
• 検索対象は自分で管理できます。 検索対象はエンジンの設定で決まるため、検索結果やランキングは google.com と異なる場合があります。
• キーはヘッダー内に保持されます。 API キー認証を使用します。OAuth やスコープは不要です。キーは X-Goog-Api-Key ヘッダーで送信され、URL には表示されません。
• Google Search Console ではありません。 自分のサイトがどのようにインデックス登録され、ランキングされているかを確認することはできません。

まずは、読み取り専用の質問から始めましょう。

先月のパスキー導入に関する最近の記事を探し、上位3件の結果を要約してください。

サーバーを接続 · ユースケースを見る · 技術ドキュメントを開く

1分で動作を確認

あなた： 先月のパスキー導入に関する最近の記事を、英語だけで探してください。

アシスタント： エンジンを使って1回検索し、それぞれの結果のタイトル、リンク、スニペットを表示します。何も変更されません。すべてのツールが読み取り専用です。

あなた： 次のページを表示してください。

アシスタント： next_start カーソルから続けて、同じクエリの検索結果11～20件を表示します。

あなた： 次に、同じトピックの大きな報道写真を探してください。

アシスタント： 画像検索に切り替え、画像ファイルとその寸法、サムネイル、掲載ページを返します。

目次

• クイックスタート
• 依頼できること
• 検索の仕組み
• 変更される可能性があるもの
• アクセスの取得
• 設定
• データ、制限、バックグラウンド処理
• 技術ドキュメント
• サポート

クイックスタート

Node.js 20 以降、Custom Search API が有効になっている Google Cloud API キー、および Programmable Search Engine の ID（cx）が必要です。

1. API キーとエンジン ID を取得する。
2. AI アプリにサーバーを追加します。
3. 上記の読み取り専用の質問をします。

codex mcp add google-custom-search \
  --env GOOGLE_CUSTOM_SEARCH_API_KEY=your_api_key \
  --env GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your_engine_id \
  -- npx -y mcp-google-custom-search@latest

codex mcp list

claude mcp add \
  --env GOOGLE_CUSTOM_SEARCH_API_KEY=your_api_key \
  --env GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your_engine_id \
  --transport stdio --scope user google-custom-search \
  -- npx -y mcp-google-custom-search@latest

claude mcp list

{
  "mcpServers": {
    "google-custom-search": {
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "your_api_key",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your_engine_id"
      }
    }
  }
}

{
  "mcpServers": {
    "google-custom-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "your_api_key",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your_engine_id"
      }
    }
  }
}

{
  "servers": {
    "google-custom-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "${input:custom_search_api_key}",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "${input:custom_search_engine_id}"
      }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "custom_search_api_key", "description": "Google Cloud API key", "password": true },
    { "type": "promptString", "id": "custom_search_engine_id", "description": "Programmable Search Engine id (cx)" }
  ]
}

何を依頼できるか

ウェブを検索する

• トピックに関する最近のチュートリアルを見つけ、上位の検索結果を要約します。
• docs.python.org 内だけを検索するか、信頼できないサイトを除いて検索します。
• 同じクエリの次のページの検索結果を表示します。

検索結果を絞り込む

• 過去 1 か月以内に公開された英語のページだけを対象にします。
• PDF ファイルだけを対象にし、完全一致するフレーズを必須にしたり、語句を除外したりします。
• 1 か国のコンテンツに限定するか、特定の使用権を持つ資料に絞ります。

画像を見つける

• トピックに関する大きな写真を、寸法やサムネイルとともに見つけます。
• クリップアートまたは線画だけ、あるいは白黒の画像だけを対象にします。
• 各画像が掲載されているページを表示します。

型付きツールの機能を超えて利用する

• 型付きツールでは公開されていないパラメーターを使って API を呼び出します。たとえば、応答を絞り込む fields、lowRange／highRange、hq を使用します。
• プロモーションと完全な pagemap を含む、生の応答エンベロープを取得します。

検索の仕組み

1. すべてのクエリは、cx IDで識別されるProgrammable Search Engineを通じて実行されます。使用されるのは、設定済みのデフォルトエンジン、または呼び出しごとに指定するengine_idです。検索対象はエンジンの設定で決まり、特定サイトのリスト、または「ウェブ全体を検索」が有効な場合はウェブ全体です。
2. 結果は、タイトル、URL、スニペット、メタデータに正規化されて返され、ページネーション用のnext_start／previous_startカーソルが含まれます。total_resultsはGoogleによる推定値であり、ページを進める間に減少することがあります。
3. APIが1回の呼び出しで返す結果は最大10件、1つのクエリにつき最大100件です（start + num - 1は100以下でなければなりません）。サーバーはリクエスト前に範囲が広すぎる場合は拒否します。APIに送信すると、割り当て枠を1単位消費した後で400が返るためです。
4. 画像検索には、エンジンのコントロールパネルで画像検索を有効にする必要があります。有効でない場合、APIは400を返します。

レスポンスのcorrected_queryはスペルの候補にすぎず、結果は元のクエリに対するものです。また、これはProgrammable Searchであり、Google Search Consoleではありません。APIでは、自サイトのインデックス登録状況や検索順位を確認できません。

変更される内容

例外的な手段も含め、すべてのツールに読み取り専用の注釈が付いています。Custom Search JSON APIは書き込み機能のない単一のGETエンドポイントであるため、呼び出しで消費されるのは1日あたりの割り当て枠だけです。

アクセスの取得

Google Custom Searchの認証にはAPIキーを使用します。OAuthやスコープは必要ありません。

1. Google Cloudプロジェクトを作成するか選択し、Custom Search APIを有効にします。
2. API とサービス → 認証情報でAPIキーを作成します。キーをCustom Search APIのみに制限しておくと安心です。
3. コントロールパネルでProgrammable Search Engineを作成し、検索エンジン ID（cx）をコピーします。オープンウェブ検索ではウェブ全体を検索を、画像ツールでは画像検索を有効にします。

APIキーはパスワードとして扱ってください。サーバーはキーをURLではなくX-Goog-Api-Keyヘッダーで送信するため、ログに記録されたURLや表示されたURLからキーが漏れることはありません。

設定

認証情報がなくてもサーバーは起動してMCPハンドシェイクを完了します。最初のツール呼び出しで、設定する変数が具体的に説明されます。設定の不備となるのは、APIキーなしでエンジンIDだけを指定する場合です。キーは呼び出しごとに指定できないため、両方をセットで設定する必要があります。

データ、上限、バックグラウンド処理

• リクエストは Google に送信されます。 ローカルサーバーは Custom Search JSON API を呼び出します。匿名のテレメトリには、インストール ID、パッケージのバージョン、AI クライアントとプラットフォームのバージョン、ツール名が含まれますが、API キー、検索クエリ、検索結果、ツールの引数は含まれません。オプトアウトするには、ASKADS_TELEMETRY=0 を設定してください。
• Google には 1 日あたりの割り当てがあります。 3 つのツールのいずれからの呼び出しも、プロジェクトごとの割り当てを 1 単位消費します。無料枠は 1 日あたり 100 クエリで、課金を有効にすると 1 日あたり最大 10,000 クエリまで利用できます。429 が返された場合、サーバーは Retry-After に従ってバックオフします。API のすべての呼び出しは冪等な GET であるため、5xx エラーやネットワークエラーも再試行されますが、400／403 はすぐに失敗します。
• バックグラウンドでのポーリングはありません。 サーバーは呼び出された場合にのみ実行されます。AI アプリがスケジュールタスクに対応している場合、定期的に検索を再実行できます。各実行で引き続き割り当て単位が消費されます。

技術ドキュメント

• MCP 機能カタログ — 各ツールのタスク別ページ。
• すべてのツールと入力
• 開発ドキュメント
• 公開ドキュメント
• Custom Search JSON API リファレンス

サポート

バグを見つけた場合や、利用シナリオが必要な場合は、Issue を作成するか、Telegram にご連絡ください。

最後までご覧いただき、ありがとうございます！