SerpApi MCP Server

SerpApi MCP Server

一个 Model Context Protocol（MCP）服务实现，可集成 SerpApi，提供全面的搜索引擎结果和数据提取功能。

功能

• 多引擎搜索：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 密钥。你可以在 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 在本地运行服务。该 bundle 使用 MCPB uv 运行时：其中仅包含源代码、pyproject.toml 和 uv.lock；Claude Desktop 会在安装时使用 uv 配置 Python 和锁定的依赖项，因此不会将任何内容打包进 bundle，同一个 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 发布版本中。拉取请求会运行 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 和 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 的客户端会在执行任何搜索前收到一个表单。已接受的答案会经过验证；拒绝或取消操作不会执行搜索。旧版客户端和不支持表单引导的客户端会收到一条列出缺失参数的错误，以便 Agent 在对话中询问。请参阅 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 请求都会应用身份验证，且只会使用针对所请求字段的答案。如果答案引入了其他要求，工具会列出剩余字段，让 Agent 在新的调用中提供。

要扩展引导式搜索，请将必填字段、描述、类型和选项添加到引擎的 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 路径中的密钥可能会出现在请求日志中，因此建议使用请求头。
• 本地套件：Claude Desktop 扩展在你的计算机上运行，将密钥保存在 Claude Desktop 的设置中，并直接调用 serpapi.com。所有内容都不会经过 mcp.serpapi.com。
• 联系：[email protected]，或提交 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 文件。