简体中文 | English

tavily-rotator-mcp

本地 Tavily MCP server：把多把免费 Tavily key 池化，round-robin 轮询 + 故障转移， 直接调用 Tavily REST API（api.tavily.com），无状态、无外部依赖服务。

特性

• 轮询：round-robin 分发请求，优先跳过冷却中的 key

• 故障转移：429 限流冷却 60s；401/432/433（无效/配额用尽）冷却 1h 后自动再探测；单次请求内自动换 key 重试

• 官方工具对齐：工具名、参数、默认值与官方托管 MCP（mcp.tavily.com）1:1 一致，模型用起来无差别

• 中心配置：key 只配一次（一行命令或一个 JSON 文件），所有 agent 共享；加 key 不用改任何客户端

• 命令行管理：tavily-rotator-mcp init / add / list，不用手动编辑配置文件

• 零端口：stdio 传输，被宿主进程拉起，不监听端口

Related MCP server: tavily-proxy-mcp

安装

需要 uv（它会顺带帮你管理 Python，本机无需预装）：

git clone https://github.com/dragonheartcra/tavily-rotator-mcp
cd tavily-rotator-mcp
uv tool install .

配置 key

方式 A：一行命令写入中心配置（推荐，配一次所有 agent 共享）

tavily-rotator-mcp init tvly-dev-xxxx tvly-dev-yyyy tvly-dev-zzzz
# 以后加新 key（自动去重）：
tavily-rotator-mcp add tvly-dev-new
# 查看已配置的 key：
tavily-rotator-mcp list

方式 B：key 直接写进 MCP 配置（单 agent 一步到位，跟配官方 tavily MCP 一样直观）

{
  "mcpServers": {
    "tavily-rotator": {
      "type": "stdio",
      "command": "tavily-rotator-mcp",
      "env": {
        "TAVILY_KEYS": "tvly-dev-xxxx,tvly-dev-yyyy"
      }
    }
  }
}

方式 B 的 env 优先级高于中心配置文件，只对这一个客户端生效，适合临时测试或按 agent 隔离 key。两种方式都没配时，server 启动会直接报错并给出提示。

各客户端接入

ZCode / Cursor / Cline 等（JSON 配置）：

{
  "mcpServers": {
    "tavily-rotator": {
      "type": "stdio",
      "command": "tavily-rotator-mcp"
    }
  }
}

Claude Code（CLI）：

claude mcp add tavily-rotator -- tavily-rotator-mcp

工具列表

与官方托管 MCP（mcp.tavily.com）的工具清单、参数、默认值对齐：

更新 / 卸载

uv tool install --force .   # 升级
uv tool uninstall tavily-rotator-mcp

注意

• key 仅用于向 Tavily API 发送 Authorization 请求头，不会被记录或发送到其他任何地方

• 通过轮换器使用多个免费账号会放大免费额度——这处于 Tavily 服务条款的灰色地带，个人轻度使用无妨，别拿它做商业用途

许可证

MIT