SerpApi MCP

SerpApi MCP 服务器

一个模型上下文协议（MCP）服务器实现，与 SerpApi 集成，提供全面的搜索引擎结果和数据提取功能。

功能特性

• 多引擎搜索：Google、Bing、Yahoo、DuckDuckGo、YouTube、eBay 以及 更多
• 引擎资源：通过 MCP 资源提供各引擎的参数模式（参见搜索工具）
• 实时天气数据：通过搜索查询提供基于位置的天气及预报
• 股票市场数据：通过搜索集成获取公司财务和市场数据
• 动态结果处理：自动检测并格式化不同类型的结果
• 灵活的响应模式：完整或紧凑的 JSON 响应
• JSON 响应（默认）：结构化 JSON 输出，支持完整或紧凑模式
• Markdown 响应：平均减少 50% 的令牌使用量，对于具有复杂嵌套 JSON 的 API 可减少超过 90%
• 交互式界面（MCP 应用）：可选的 search_table 和 search_dashboard 工具，在支持的宿主中将结果渲染为交互式界面
• Claude Desktop 扩展：从 MCP 捆绑包（.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 捆绑包）

如需本地一键安装，请从 最新版本 下载 .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，将 git 跟踪的文件（减去 .mcpbignore）与清单一起打包到捆绑包根目录，然后将其安装到临时目录并通过 stdio 启动以确保其正常工作（--no-smoke 跳过最后一步）。捆绑包仅在发布时构建：推送 v<version> 标签会运行发布工作流，该工作流运行测试套件，然后部署托管服务器、发布 MCP 注册表条目、构建捆绑包并将其附加到 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" }
    }
  }
}

身份验证

支持两种方法：

• 基于请求头：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：出发地和到达地标识符、出发日期，以及往返行程的返回日期。日期和机场标识符会被检查。基于令牌的搜索、多城市行程和 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。

交互式界面（MCP 应用）

search 工具默认返回 JSON。对于支持 MCP 应用扩展（SEP-1865）的宿主，两个可选工具直接在对话中渲染交互式界面，因此大量 SERP JSON 不会进入模型的上下文窗口：

• search_table：自然结果以可排序、可搜索的表格呈现。
• search_dashboard：摘要指标、来源分布图表，以及带点击展开详情面板的结果表格。

两者接受与 search 相同的 params。不支持 MCP 应用的宿主会直接忽略这些工具。

无需 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。
• 联系：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. 打开拉取请求

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。