SerpApi MCP

官方

SerpApi MCP Server 用

GitHub
175
試用此 MCP贊助

你可以用 SerpApi MCP 做什麼？

  • 多引擎搜尋 — 透過 search 工具並搭配引擎特定參數，向 Google、Bing、YouTube、eBay 或其他引擎請求結果。
  • 結構化結果格式 — 要求 JSON 或 Markdown 輸出，並可選擇精簡或完整模式，以控制回應詳細程度與 token 用量。
  • 互動式結果檢視 — 在支援的主機中使用 search_table 取得可排序表格，或使用 search_dashboard 取得圖表與可展開的詳細資訊。
  • 即時資料查詢 — 以自然語言查詢，例如「倫敦天氣」或「AAPL 股票」，取得天氣預報、股價或新聞。
  • 引導式參數完成 — 在搜尋執行前，針對缺少的必填欄位（例如航班日期、飯店入住/退房）提供表單。

文件

SerpApi MCP 伺服器

一個模型上下文協定（MCP）伺服器實作，整合 SerpApi 以提供全面的搜尋引擎結果與資料擷取功能。

Python 3.13+ MIT License Install in VS Code Install in Cursor

功能特色

  • 多引擎搜尋：Google、Bing、Yahoo、DuckDuckGo、YouTube、eBay 及更多
  • 引擎資源：每個引擎的參數結構可透過 MCP 資源取得（請參閱搜尋工具）
  • 即時天氣資料：透過搜尋查詢提供基於位置的天氣與預報
  • 股票市場資料：透過搜尋整合取得公司財務與市場資料
  • 動態結果處理：自動偵測並格式化不同類型的結果
  • 彈性回應模式：完整或精簡的 JSON 回應
  • JSON 回應（預設）：結構化 JSON 輸出，提供完整或精簡模式
  • Markdown 回應：平均減少 50% 的 token 使用量，對於具有複雜巢狀 JSON 的 API 可減少超過 90%
  • 互動式 UI（MCP 應用程式）：可選擇啟用 search_table 和 search_dashboard 工具，在支援的主機中將結果呈現為互動式 UI
  • Claude Desktop 擴充功能：可從 MCP Bundle（.mcpb）一鍵本地安裝，詳見下文

快速開始

SerpApi MCP 伺服器可作為託管服務使用，網址為 mcp.serpapi.com。若要連線，您需要提供 API 金鑰。您可以在 SerpApi 儀表板 找到您的 API 金鑰。

您可以設定 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（從您 shell 中的 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 Bundle）

若要進行本地一鍵安裝，請從最新版本下載 .mcpb bundle（或依下文方式建置），然後使用 Claude Desktop 開啟（或將其拖曳至 設定 → 擴充功能）。Claude Desktop 會在安裝期間要求您提供 SerpApi API 金鑰，將其儲存為敏感設定，並透過 stdio 在本地執行伺服器。該 bundle 使用 MCPB uv 執行環境：僅包含原始碼、pyproject.toml 和 uv.lock，Claude Desktop 會在安裝時使用 uv 提供 Python 和鎖定的相依套件，因此不會捆綁任何內容，且同一個 bundle 可在 macOS、Windows 和 Linux 上運作。

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

所有與 bundle 相關的內容都位於 mcpb/，以及專案根目錄的 .mcpbignore。建置過程會從 SerpApi Playground 重新產生引擎結構（--no-rebuild-engines 改為從工作樹捆綁 engines/），驗證 mcpb/manifest.json，將 git 追蹤的檔案（扣除 .mcpbignore）與 manifest 一起打包至 bundle 根目錄，然後安裝到暫存目錄並透過 stdio 啟動以確保其正常運作（--no-smoke 會跳過最後一步）。Bundle 僅在發布時建置：推送 v<version> 標籤會執行發布工作流程，該流程會執行測試套件，然後部署託管伺服器、發布 MCP Registry 條目，並建置 bundle 且附加至 GitHub 發布。Pull requests 會在 tests/test_mcpb.py 中執行 manifest 和 stdio 進入點測試，但不會打包 bundle。

相同的 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" }
    }
  }
}

驗證

支援兩種方法：

  • 基於標頭：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 和應用程式工具需要金鑰，若缺少金鑰則會回傳錯誤。

搜尋工具

MCP 伺服器有一個主要的搜尋工具，支援所有 SerpApi 引擎和結果類型。您可以在 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（預設），或設定為 "md" 以取得 Markdown
  • 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：出發和抵達識別碼、出發日期，以及來回程的回程日期。會檢查日期和機場識別碼。基於 token 的搜尋、多城市行程和 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）的主機，有兩個可選擇啟用的工具會直接在對話中將結果呈現為互動式 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 路徑中的金鑰可能出現在請求日誌中，因此建議使用標頭。
  • 本地 bundle：Claude Desktop 擴充功能在您的機器上執行，將金鑰保留在 Claude Desktop 的設定中，並直接呼叫 serpapi.com。不會有任何內容通過 mcp.serpapi.com。
  • 聯絡方式：privacy@serpapi.com，或開啟 issue。

貢獻

  1. Fork 儲存庫
  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. 開啟 Pull Request

授權

MIT 授權 — 詳情請參閱 LICENSE 檔案。