SerpApi MCP

SerpApi MCP Server

一个模型上下文协议 (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 扩展：通过 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 扩展（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：出发地和目的地标识符、出发日期，以及往返行程的返程日期。日期和机场标识符会经过检查。基于令牌的搜索、多城市行程和 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 扩展在你的计算机上运行，将密钥保存在 Claude Desktop 的设置中，并直接调用 serpapi.com。任何内容都不会经过 mcp.serpapi.com。
• 联系：privacy@serpapi.com，或提交一个问题。

贡献

有关开发环境设置、架构刷新命令、测试、Docker 和 MCP Bundle 构建以及发布的信息，请参阅 CONTRIBUTING.md。

许可证

MIT License - 详情请参阅 LICENSE 文件。