SerpApi MCP

SerpApi MCP Server

一個 Model Context Protocol (MCP) 伺服器實作，整合 SerpApi，提供全面的搜尋引擎結果與資料擷取功能。

功能

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

快速開始

SerpApi MCP Server 提供託管服務，網址為 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 Extension（MCP bundle）

若要在本機一鍵安裝，請從最新版本下載 .mcpb bundle，並使用 Claude Desktop 開啟（或將其拖放至 Settings → Extensions）。Claude Desktop 會在安裝期間要求您提供 SerpApi API 金鑰，將其儲存為敏感設定，並透過 stdio 在本機執行伺服器。安裝時會使用 uv 安裝 Python 和相依套件。同一個 bundle 適用於 macOS、Windows 和 Linux。

任何會以子程序方式啟動伺服器的本機 MCP 主機，都可以使用相同的 stdio 進入點：

{
  "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 和 App 工具需要金鑰，若未提供則會傳回錯誤。

搜尋工具

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 引用搜尋。

如果答案引入其他必要條件，工具會列出剩餘欄位，供代理程式在新的呼叫中提供。表單支援字串、數字、布林值和單選欄位；不支援的複雜欄位會傳回缺少參數錯誤。未知引擎會直接傳遞至 SerpApi。

擷取工具

extract 工具會讀取網頁，並以結構化 JSON 或 Markdown 傳回內容。您可以擷取單一頁面、探索網站 URL，或爬取多個頁面。請在 Extract API 參考 或 serpapi://engines/extract 資源中查看所有可用參數。

可提供的部分參數：

• params.url（必填）：頁面或網站 URL
• params.mode：擷取模式；"scrape"（預設值）會讀取單一頁面，"map" 會探索 URL，而 "crawl" 會擷取多個頁面
• params.include_markdown：以 Markdown 格式包含頁面內容；擷取和爬取時預設為 true，或設為 false 以停用
• params.output：回應格式；完整模式預設為 "json"，精簡模式預設為 "md"。明確設定此參數可覆寫格式。
• params.max_pages：爬取的頁面上限，包含起始頁面（預設值：10，最大值：100）
• params.json_restrictor：選擇要傳回的欄位，例如 "markdown,error"
• mode：回應模式；"complete"（預設值）會傳回完整回應。"compact" 預設為原生 Markdown。明確指定 params.output="json" 時，單頁精簡擷取會在存在時保留頂層 markdown 欄位，並保留 API 錯誤。沒有 Markdown 的回應（包括重新導向至其他引擎的結果）會保留其資料並移除中繼資料。使用 JSON 時，明確指定的 params.json_restrictor 值和 params.include_markdown=false 具有優先權。對於地圖和爬取，精簡 JSON 會移除中繼資料。Markdown 輸出維持不變。

範例：

{"name": "extract", "arguments": {"params": {"url": "https://example.com"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com"}, "mode": "compact"}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "output": "md"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "map"}}}
{"name": "extract", "arguments": {"params": {"url": "https://example.com", "mode": "crawl", "max_pages": 2}}}

若要以原生 Markdown 取得單一頁面的內容，請使用 mode="compact"。加入 params.output="json" 可改為接收包含 markdown 欄位的 JSON。完整 JSON 預設會包含該欄位；爬取 JSON 則會在每個 pages 項目中包含該欄位。設定 params.output="json" 和 params.include_markdown=false 可保留其餘結構化欄位，但不包含 Markdown。

對於未快取的請求，每成功擷取一個頁面，爬取作業會消耗一個搜尋額度。使用 params.max_pages 限制擷取頁面數量。

互動式 UI（MCP apps）

search 工具預設會傳回 JSON。對於支援 MCP Apps 擴充功能（SEP-1865）的主機，兩個可選用的工具會直接在對話中以互動式 UI 呈現結果，因此大量 SERP JSON 不會進入模型的上下文視窗：

• search_table：將自然搜尋結果呈現為可排序、可搜尋的表格。
• search_dashboard：呈現摘要指標、來源分布圖表，以及可點擊展開詳細資訊面板的結果表格。

兩者都接受與 search 相同的 params。不支援 MCP Apps 的主機會直接忽略這些工具。

疑難排解

• 「缺少 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 extension 會在您的電腦上執行，將金鑰保存在 Claude Desktop 的設定中，並直接呼叫 serpapi.com。任何資料都不會經過 mcp.serpapi.com。
• 聯絡方式：privacy@serpapi.com，或提交問題。

參與貢獻

請參閱 CONTRIBUTING.md，了解開發環境設定、結構描述更新命令、測試、Docker 和 MCP Bundle 建置，以及版本發佈。

授權條款

MIT License——詳情請參閱 LICENSE 檔案。