search-rotation

一个 MCP 服务，整合多个提供商的网页搜索与页面提取功能。

由 Robin Bially 构建。

在可用配额之间轮换；当某个提供商不可用时自动故障转移，并向 AI 助手返回一致的结果。本地仪表板可用于管理 API 密钥、调整引擎顺序、查看配额和检查请求历史记录。

实际仪表板界面，以英文显示并使用示例数据。调用次数与提供商预算分开显示；活动条可展示不同时间范围和各引擎的详细信息。

快速开始

npm

npx -y search-rotation --http --open

需要 Node.js 20.3+。要通过 stdio 使用 MCP，请将客户端配置为不带参数运行 npx -y search-rotation。该服务也已列入 官方 MCP Registry， 名称为 io.github.robin-bially/search-rotation。

Homebrew

brew install robin-bially/tap/search-rotation
search-rotation --http --open

Homebrew 会安装所需的 Node.js 运行时。要通过 stdio 使用 MCP，请将客户端配置为不带参数运行 search-rotation。有关升级和详情，请参阅 Homebrew tap。

从 GitHub 安装固定版本

npx -y --allow-git=all github:robin-bially/search-rotation-mcp#v0.5.2

如果你想使用固定版本，而不是当前的 npm 发行版，请使用此方式。

在仪表板中添加提供商密钥，然后参阅面向 Codex、Claude、Cursor 或 OpenCode 的 MCP 客户端设置指南，连接你的助手。

功能

• 搜索与提取： 网页搜索和 Markdown 页面提取分别独立轮换。
• 自动故障转移： 根据配额调整顺序、速率限制冷却时间和请求超时。
• 本地仪表板： API 密钥、拖放式引擎排序、各引擎的调用次数与错误、单独的配额余额以及交互式请求历史记录。
• 本地或远程： 通过 stdio 或经过身份验证的 Streamable HTTP 使用 MCP。

提供商： Tavily · Firecrawl · Parallel · Exa · Google PSE · Jina Reader · DuckDuckGo HTML。免密钥访问与配额统计因提供商而异。

MCP 工具

search_web · fetch_url · get_engine_status · update_engine_config · open_dashboard

每个名称都将一个操作与其目标配对。update_engine_config 涵盖仪表板引擎列表中的功能：启用和停用引擎、设置搜索和提取的轮换顺序，以及设置每个引擎的月度或每日限额。API 密钥保留在仪表板中。如果你的客户端维护着工具名称允许列表，请将其中较早的 web_search 和 engine_status 条目替换掉。

仪表板的 MCP Tools 选项卡会介绍每个工具及其参数，并提供可复制的示例调用。

实际仪表板界面，以英文显示。

搜索时间筛选

search_web 接受以下参数：

参数	含义
query	必填搜索文本。
numResults	可选结果数量，范围为 1–20；否则使用仪表板设置。
engine	首选提供商，受时间筛选支持情况和可用性限制；故障转移仍保持启用。
timeRange	day、week、month 或 year：从 1、7、30 或 365 天前开始，至今天为止的 UTC 日期范围。
startDate	可选下限日期，格式为 YYYY-MM-DD。
endDate	可选上限日期，格式为 YYYY-MM-DD。

使用 timeRange 或明确指定日期。允许仅设置一侧边界，也允许开始日期和结束日期相同；无效日历日期、逆序边界，以及混合使用相对筛选和明确日期筛选，都会在请求任何提供商之前被拒绝。

{"name":"search_web","arguments":{"query":"AI inference research","timeRange":"week","numResults":5}}

{"name":"search_web","arguments":{"query":"AI inference research","startDate":"2026-08-01","endDate":"2026-08-31"}}

相对时间范围会在每个请求中仅解析一次为 UTC 日期，包括发生故障转移时。这些是日期筛选条件，而非精确滚动的 24 小时时间范围；month 和 year 分别表示 30 天和 365 天，而不是按日历计算。Exa 接收 UTC 首日的起始时间和末日的结束时间。

提供商支持与轮换

提供商 / 访问方式	相对时间范围	两个日期边界	一个日期边界
Tavily，有或没有密钥	是	是	是
Firecrawl，有或没有密钥	是	是	跳过
Exa，使用密钥的直接 API	是	是	是
Exa，无密钥的托管 MCP	跳过	跳过	跳过
Parallel，任一访问方式	跳过	跳过	跳过
Google PSE / DuckDuckGo HTML	跳过	跳过	跳过

此表描述的是 search-rotation 中已实现的支持，并非所有上游功能。Tavily 接收 start_date / end_date，Firecrawl 接收自定义 tbs 范围，Exa 接收 startPublishedDate / endPublishedDate。Firecrawl 对仅设置一侧边界的情况采取保守做法，不予使用；其他被跳过的路径则尚未实现日期映射。

路由器会在配额检查和轮换之前排除不兼容的提供商，即使首选的 engine 不兼容也是如此。每个符合条件的提供商池都有自己的轮换游标，因此混合使用带时间筛选和不带时间筛选的搜索不会导致提供商无法获得请求。现有的配额优先级、冷却机制、严格免费规则和故障转移均在该池内生效。如果没有可用的兼容提供商，搜索会明确失败；绝不会在不带筛选条件的情况下重试。不带时间参数的搜索仍可使用所有其他符合条件的提供商。

如果适配器提供了发布日期，结果就会显示该日期；请求历史记录也会包含所请求的时间范围。提供商的日期元数据可能是估算值，也可能缺失：Tavily 按发布日期或更新日期筛选，Exa 按估算的发布日期筛选，Firecrawl 则使用其搜索索引对日期的解释。边界是否包含由提供商决定；这并不代表会独立验证每个页面的发布日期。请参阅 Tavily、Firecrawl 和 Exa 文档。

更新后，请重新连接 MCP 客户端以加载新的工具架构。

发布

VERSION=0.4.10 ./scripts/release.sh --publish

该脚本会检查软件包（npm ci、构建、测试、npm run smoke:package），更新版本号，将文档中的版本固定值指向该版本，提交并打标签，打包 tarball 并生成校验和，创建 GitHub 发布，在 robin-bially/homebrew-tap 中更新 formula，最后等待 npm 注册表提供新版本。不带 --publish 时，脚本只会在 .build/releases 中准备发布产物；--dry-run 会检查前置条件，--draft 会创建草稿发布，--force 则允许工作区存在未提交的更改。如果未设置 TAP_DIR，脚本会临时克隆 tap，因此只需全新检出即可。

发布到 npm 会在 GitHub 发布正式发布后，通过 .github/workflows/publish.yml 中的可信发布完成，因此脚本本身无需 npm 凭据。该工作流要求在 npmjs.com 上为 search-rotation 配置可信发布者，并将其指向此仓库和 publish.yml。

同一工作流还会根据 server.json 在官方 MCP Registry 中登记该版本。分发与列表会跟踪各个渠道、负责维护的人员，以及每个渠道仍需完成的事项。

了解更多

客户端设置 · 运维与配置（DE） · 分发与列表 · 发布 · CI · MIT 许可证