SerpApi Mcp

SerpApi MCP サーバー

包括的な検索エンジンの検索結果とデータ抽出を実現するため、SerpApi と連携する Model Context Protocol（MCP）サーバーの実装です。

特長

• 複数エンジンでの検索：Google、Bing、Yahoo、DuckDuckGo、YouTube、eBay、その他の検索エンジン
• エンジンのリソース：エンジンごとのパラメータスキーマを MCP リソースから利用できます（検索ツールを参照）
• リアルタイムの気象データ：検索クエリを使って、場所に応じた天気と予報を取得できます
• 株式市場データ：検索連携を通じて、企業の財務情報と市場データを取得できます
• 動的な結果処理：さまざまな種類の結果を自動で検出し、形式を整えます
• 柔軟なレスポンスモード：完全または簡潔な JSON レスポンス
• JSON レスポンス（デフォルト）：完全モードまたは簡潔モードで、構造化された JSON を出力します
• Markdown レスポンス：トークン使用量を平均で 50％、複雑なネスト構造を持つ JSON の API では 90％以上削減します
• インタラクティブ UI（MCP Apps）：オプトインの search_table および search_dashboard ツールを使うと、対応ホストで結果をインタラクティブな UI として表示できます
• Claude Desktop 拡張機能：MCP Bundle（.mcpb）からワンクリックでローカルにインストールできます。詳細は以下を参照してください

クイックスタート

SerpApi MCP Server は、mcp.serpapi.com でホスト型サービスとして利用できます。接続するには、API キーを指定する必要があります。API キーはSerpApi ダッシュボードで確認できます。

ホスト型サーバーを使用するように Claude Desktop を設定できます。

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

次の MCP クライアントにもホスト型サーバーを追加できます。

OpenClaw

openclaw mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp --transport streamable-http

Claude Code

claude mcp add --transport http serpapi https://mcp.serpapi.com/mcp --header "Authorization: Bearer YOUR_SERPAPI_API_KEY"

Hermes

hermes mcp add serpapi --url https://mcp.serpapi.com/YOUR_SERPAPI_API_KEY/mcp

Codex（シェルの SERPAPI_API_KEY からキーを読み込みます）

codex mcp add serpapi --url https://mcp.serpapi.com/mcp --bearer-token-env-var SERPAPI_API_KEY

セルフホスト

git clone https://github.com/serpapi/serpapi-mcp.git
cd serpapi-mcp
uv sync && uv run src/server.py

Claude Desktop を設定します。

{
  "mcpServers": {
    "serpapi": {
      "type": "http",
      "url": "http://localhost:8000/YOUR_SERPAPI_API_KEY/mcp"
    }
  }
}

API キーの取得：serpapi.com/manage-api-key

Claude Desktop 拡張機能（MCP バンドル）

ローカルにワンクリックでインストールするには、最新リリースから.mcpbバンドルをダウンロードするか、以下の手順でビルドし、Claude Desktopで開きます（または設定 → 拡張機能にドロップします）。インストール中にClaude DesktopからSerpApi APIキーの入力を求められます。キーは機密設定として保存され、サーバーはstdio経由でローカル実行されます。このバンドルではMCPBのuvランタイムを使用します。ソース、pyproject.toml、uv.lockのみが含まれており、Claude Desktopがインストール時にuvを使ってPythonとロックされた依存関係を用意するため、ベンダー化されたファイルは含まれず、macOS、Windows、Linuxで同じバンドルを使用できます。

uv run mcpb/build.py   # needs Node.js for the MCPB CLI; writes dist/serpapi-mcp-<version>.mcpb

バンドルに関するファイルはすべてmcpb/と、プロジェクトルートにある.mcpbignoreにまとめられています。ビルド時にはSerpApi Playgroundからエンジンスキーマを再生成します（--no-rebuild-enginesを指定すると、作業ツリー内のengines/をバンドルします）。続いて mcpb/manifest.jsonを検証し、.mcpbignoreに記載されたファイルを除いたGit管理対象ファイルを、マニフェストをバンドルのルートに置いてパッケージ化します。その後、一時ディレクトリにインストールしてstdio経由で起動し、正常に動作することを確認します（--no-smokeを指定すると、この最後の手順を省略します）。バンドルをビルドするのはリリース時のみです。v<version>タグをプッシュするとリリースワークフローが実行され、テストスイートを実行した後、ホスト型サーバーをデプロイし、MCP Registryのエントリーを公開し、バンドルをビルドしてGitHubリリースに添付します。プルリクエストではtests/test_mcpb.pyにあるマニフェストとstdioエントリーポイントのテストを実行しますが、バンドルのパッケージ化は行いません。

同じstdioエントリーポイントは、サーバーをサブプロセスとして起動する任意のローカルMCPホストで動作します。

{
  "mcpServers": {
    "serpapi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/serpapi-mcp", "--frozen", "--no-dev", "src/stdio.py"],
      "env": { "SERPAPI_API_KEY": "YOUR_SERPAPI_API_KEY" }
    }
  }
}

認証

次の2つの方法に対応しています。

• ヘッダーベース：Authorization: Bearer YOUR_API_KEY（推奨：キーがURLやログに含まれません）
• パスベース：/YOUR_API_KEY/mcp（ヘッダーを設定できないクライアント向け）

例：

# Header-based
curl "https://mcp.serpapi.com/mcp" -H "Authorization: Bearer your_key" -d '...'

# Path-based
curl "https://mcp.serpapi.com/your_key/mcp" -d '...'

接続、ツールの一覧表示、リソースの読み取りにはキーは不要です。searchとAppツールにはキーが必要で、キーがない場合はエラーを返します。

検索ツール

MCP サーバーには、SerpApiのすべてのエンジンと結果タイプに対応するメインの検索ツールが1つあります。利用可能なすべてのパラメーターはSerpApi APIリファレンスで確認できます。 エンジンパラメータのスキーマはMCPリソースとしても公開されています：serpapi://engines（インデックス）とserpapi://engines/<engine>。 引数補完に対応するクライアントは、serpapi://engines/{engine_name}に対するエンジン名の候補をリクエストできます。たとえば、プレフィックスgoogle_fを指定すると、一致するエンジン識別子が候補として表示されます。これはリソースURIのパラメーターを補完するもので、任意の検索クエリを補完する機能ではありません。

指定できるパラメーターはAPIエンジンごとに異なります。パラメーターの例を以下に示します。

• params.q（必須）：検索クエリ
• params.engine：検索エンジン（デフォルト：「google_light」）
• params.location：地域フィルター
• params.output：レスポンス形式。JSONの場合は省略（デフォルト）、Markdownの場合は"md"を指定
• mode：レスポンスモード。"compact"を指定するとJSONからメタデータが除かれます。Markdownは変更されません
• …その他のパラメーターについてはSerpApi APIリファレンスを参照してください

例：

{"name": "search", "arguments": {"params": {"q": "coffee shops", "location": "Austin, TX"}}}
{"name": "search", "arguments": {"params": {"q": "weather in London"}}}
{"name": "search", "arguments": {"params": {"q": "AAPL stock"}}}
{"name": "search", "arguments": {"params": {"q": "news"}, "mode": "compact"}}
{"name": "search", "arguments": {"params": {"q": "detailed search"}, "mode": "complete"}}
{"name": "search", "arguments": {"params": {"q": "news", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "amazon", "k": "mechanical keyboards", "amazon_domain": "amazon.com", "output": "md"}}}
{"name": "search", "arguments": {"params": {"engine": "google_scholar", "q": "retrieval augmented generation"}}}
{"name": "search", "arguments": {"params": {"engine": "youtube", "search_query": "how to make espresso"}}}
{"name": "search", "arguments": {"params": {"engine": "apple_app_store", "term": "habit tracker"}}}
{"name": "search", "arguments": {"params": {"engine": "ebay", "_nkw": "vintage mechanical keyboard"}}}

対応エンジン： Google、Bing、Yahoo、DuckDuckGo、YouTube、eBayなど（serpapi://enginesを参照）。

結果タイプ： アンサーボックス、オーガニック検索結果、ニュース、画像、ショッピング。種類は自動的に検出され、フォーマットされます。 検索レスポンスでは、既存の MCP structuredContent.result 文字列を保持し、同じ文字列をテキストコンテンツにも含めます。JSON 出力の場合、result にはシリアライズされた JSON が含まれます。既存のクライアントは引き続き JSON.parse(response.structuredContent.result) で解析できます。Markdown 出力の場合、変更されていない Markdown が含まれます。エラーとキャンセルにも同じラッパーを使用します。検索の実行に失敗すると、isError: true が設定されます。FastMCP の高水準な call_tool() を使用するクライアントは ToolError を処理するか、call_tool_mcp() を使用して結果フラグを確認してください。MCP ツールの結果を参照してください。

search はエンジンカタログとエンジン固有のルールを使用して、不足しているパラメーターを特定します。MCP 2026-07-28 対応クライアントには、検索を実行する前にフォームが表示されます。回答は検証されます。拒否またはキャンセルされた場合、検索は実行されません。レガシークライアントやフォームの引き出しに対応していないクライアントには、不足しているパラメーターを列挙したエラーが返されるため、エージェントは会話の中で確認できます。MCP 入力リクエストを参照してください。

• Google Flights：出発地と到着地の識別子、出発日、往復の場合は帰着日が必要です。日付と空港識別子は検証されます。トークンベースの検索、複数都市の旅程、selected_flights_json は、既存の動作を維持します。
• Google Hotels：目的地またはホテルのクエリ、チェックイン日、チェックアウト日が必要です。チェックアウト日はチェックイン日より後である必要があります。宿泊者数やその他の任意のフィルターには、呼び出し元の値または API のデフォルト値が引き続き適用されます。
• Google Maps Directions：不足している出発地と目的地の住所が必要です。座標または場所データ ID がすでに指定されている場合は、対応するエンドポイントの要件を満たします。
• その他のカタログ内のエンジンでは、YouTube の search_query、Yelp の find_loc、Amazon の k など、必須フィールドが使用されます。エンジンルールでは、Amazon のカテゴリノード、eBay のカテゴリ、Google Scholar の引用検索など、既知のデフォルト値や代替手段も考慮されます。

フォームは、リクエストごとに元の引数から生成されます。requestState やプロセスローカルの継続ストレージは使用しないため、共有の状態保護キーがなくても、再試行を別のレプリカで実行できます。認証は HTTP リクエストごとに適用され、リクエストされたフィールドへの回答のみが使用されます。回答によって別の要件が生じた場合、ツールは残りのフィールドを列挙し、エージェントが新しい呼び出しで指定できるようにします。

ガイド付き検索を拡張するには、エンジンの engines/<engine>.json ファイルに必須フィールド、説明、型、選択肢を追加します。要件が他のパラメーター、デフォルト値、または代替手段に依存する場合は、src/engine_input_rules.py に EngineInputRules エントリーを追加します。src/search_input.py の共通 MCP ハンドラーに、エンジン固有の分岐を追加する必要はありません。フォームでは文字列、数値、ブール値、単一選択フィールドがサポートされます。サポートされていない複雑なフィールドには、不足パラメーターのエラーが返されます。不明なエンジンは SerpApi にそのまま渡されます。

インタラクティブ UI（MCP アプリ）

search ツールはデフォルトで JSON を返します。MCP Apps 拡張機能（SEP-1865）に対応したホストでは、オプトインで使用できる 2 つのツールが、結果を会話内に直接インタラクティブ UI として表示します。これにより、大量の SERP JSON がモデルのコンテキストウィンドウに入ることはありません。

• search_table：オーガニック検索結果を、並べ替えと検索が可能なテーブルで表示します。
• search_dashboard：概要メトリクス、ソース別内訳のチャート、クリックして詳細パネルを展開できる結果テーブルを表示します。

どちらも search と同じ params を受け付けます。MCP Apps に対応していないホストは、これらのツールを無視します。

MCP ホストなしでローカルにプレビューできます。

uv run fastmcp dev apps src/server.py

開発

# Local development
uv sync && uv run src/server.py

# Docker
docker build -t serpapi-mcp . && docker run -p 8000:8000 serpapi-mcp

# Build the Claude Desktop extension (MCP Bundle); rebuilds engines, needs Node.js for the MCPB CLI
uv run mcpb/build.py

# Release: update pyproject.toml, server.json, mcpb/manifest.json and uv.lock together.
uv run --no-sync scripts/bump_version.py 2.0.0
# Review and commit the changes before tagging the release.
# Nothing ships on a plain push to main. The tag runs the release workflow, which runs the test
# suite and then deploys the hosted server, publishes server.json to the MCP Registry, and builds
# the MCP Bundle and attaches it to the GitHub release.
git tag v2.0.0 && git push origin v2.0.0

# Regenerate engine resources (Playground scrape)
python build-engines.py

# Testing with MCP Inspector
npx @modelcontextprotocol/inspector
# Configure: URL mcp.serpapi.com/YOUR_KEY/mcp, Transport "Streamable HTTP transport"

トラブルシューティング

• 「API キーがありません」：URL パス /{YOUR_KEY}/mcp またはヘッダー Bearer YOUR_KEY にキーを含めてください
• 「無効なキーです」：serpapi.com/dashboard で確認してください
• 「レート制限を超えました」：しばらく待つか、SerpApi のプランをアップグレードしてください
• 「結果がありません」：別のクエリまたはエンジンを試してください

プライバシーポリシー

• 送信される情報：MCP ホストがツール呼び出しに渡すパラメーターのみです。サーバーは、会話の残りの部分や、ホスト上のファイル、メモリ、履歴を確認することはありません。
• 転送される情報：各検索は API キーとともに serpapi.com に送信され、結果は変更されずに返されます。SerpApi が検索とアカウントをどのように取り扱うかについては、SerpApi プライバシーポリシーをご覧ください。
• 保持される情報：mcp.serpapi.com はリクエストのメトリクス（メソッド、ステータスコード、所要時間）を記録しますが、クエリや結果は保存しません。URL パス内のキーはリクエストログに記録されることがあるため、ヘッダーの使用をおすすめします。
• ローカルバンドル：Claude Desktop 拡張機能はお使いのマシン上で実行され、キーを Claude Desktop の設定に保存し、serpapi.com を直接呼び出します。mcp.serpapi.com を経由する情報はありません。
• お問い合わせ：[email protected] に連絡するか、issue を作成してください。

コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature/amazing-feature
3. 依存関係をインストールします：uv install
4. 変更を加えます
5. 変更をコミットします：git commit -m 'Add amazing feature'
6. ブランチにプッシュします：git push origin feature/amazing-feature
7. プルリクエストを作成します

ライセンス

MIT License — 詳細は LICENSE ファイルをご覧ください。