Serper Toolkit

Serper MCP工具包

基于 firecrawl-toolkit 建筑。

亮点

• 统一异步请求层(httpx +连接池+重试）
• 紧凑的JSON响应（单行）以降低令牌使用率
• 稳定的映射响应模式（无上游原始传递）
• 非图像搜索端点的多页面聚合（10个结果/页面粒度）
• 图像搜索 search_num 标准化到 10 或 100
• 多运输启动(STDIO / HTTP / SSE，相互排斥）
• 进程锁定以防止重复的服务器实例

工具

• serper-aggregated-search
• serper-general-search
• serper-image-search
• serper-video-search
• serper-place-search
• serper-maps-search
• serper-reviews-search
• serper-news-search
• serper-lens-search
• serper-scholar-search
• serper-shopping-search
• serper-patents-search
• serper-scrape

核心参数规则

• 搜索工具可以 不 暴露 page；内部分页是自动的。
• 非图像端点：

- search_num 被夹紧 1..100 - 然后倒圆 上 精确到10的倍数(25 -> 30)

• 图像端点：

- 1..10 -> 10, 11..100 -> 100

• 地图端点：

- 当聚合要求页面>1并且使用查询模式时， ll 是必需的。

环境变量

API和网络

• SERPER_API_KEY
• SERPER_HTTP2 (0/1)
• SERPER_MAX_CONNECTIONS
• SERPER_KEEPALIVE
• SERPER_MAX_CONCURRENT_REQUESTS
• SERPER_MAX_WORKERS
• SERPER_RETRY_COUNT
• SERPER_RETRY_BASE_DELAY
• SERPER_ENDPOINT_CONCURRENCY （JSON，例如。 {"search":10,"scrape":2})
• SERPER_ENDPOINT_RETRYABLE （JSON，例如。 {"scrape":false})

传输选择（必须启用一个）

• SERPER_MCP_ENABLE_STDIO
• SERPER_MCP_ENABLE_HTTP
• SERPER_MCP_ENABLE_SSE

传输主机/端口

• SERPER_MCP_HTTP_HOST
• SERPER_MCP_HTTP_PORT
• SERPER_MCP_SSE_HOST
• SERPER_MCP_SSE_PORT
• SERPER_MCP_HOST （回退）
• SERPER_MCP_PORT （回退）

锁定文件

• SERPER_MCP_LOCK_FILE （默认值 /tmp/serper_mcp.lock 在Unix上）

MCP客户端示例

{
  "mcpServers": {
    "serper-toolkit": {
      "command": "uvx",
      "args": ["serper-toolkit"],
      "env": {
        "SERPER_API_KEY": "",
        "SERPER_MCP_ENABLE_STDIO": "1"
      }
    }
  }
}

CI/CD

包括两个GitHub Actions工作流：

• CI (.github/workflows/ci.yml)

- 触发器：按下/PR打开 main - Python矩阵： 3.12, 3.13 - 步骤：别名验证、单元测试、构建、绳线检查

• Publish to PyPI (.github/workflows/publish-pypi.yml)

- 触发器：按下 main （自动），加上手动 workflow_dispatch - 前言：别名验证、测试、构建、绳线检查、版本不在PyPI检查中 - 发布：通过OIDC向PyPI可信发布

所需的存储库设置

1. 创建GitHub环境： pypi
2. 为此仓库/工作流/分支配置PyPI可信发布服务器：

- 工作流文件： .github/workflows/publish-pypi.yml - 分行： main

1. 确保操作权限允许OIDC(id-token: write 工作流中已设置）

开发验证

python3 scripts/validate_country_aliases.py
python3 -m unittest discover -s tests -p "test_*.py"
python3 -m build
python3 -m twine check dist/*

许可证

麻省理工学院