Skip to main content
Glama
Sign In
tavily-rotator-mcp

tavily-rotator-mcp

by dragonheartcra
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

简体中文 | English

tavily-rotator-mcp

License: MIT Python 3.10+

本地 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）的工具清单、参数、默认值对齐：

工具

说明

tavily_search

网络搜索（/search，含时间范围、域名过滤、新闻/财经主题等）

tavily_extract

提取 URL 正文（/extract）

tavily_crawl

整站爬取（/crawl，深度/广度/数量可配）

tavily_map

网站结构地图（/map）

tavily_research

深度研究报告（/research，异步任务自动轮询，约 1-5 分钟）

tavily_pool_status

查看 key 池状态（成功/失败/冷却剩余），0 credit

更新 / 卸载

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

注意

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

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

许可证

MIT

Available Tools

6 tools
tavily_crawlC

Crawl a website starting from a URL. Extracts content from pages with configurable depth and breadth.

Inputs: url (required), limit, format, max_depth, +7 more. Returns: result

tavily_extractC

Extract content from URLs. Returns raw page content in markdown or text format.

Inputs: urls (required), query, format, extract_depth, +2 more. Returns: result

tavily_mapC

Map a website's structure. Returns a list of URLs found starting from the base URL.

Inputs: url (required), limit, max_depth, max_breadth, +4 more. Returns: result

tavily_pool_statusA

查看本地 key 池状态（成功/失败次数、冷却剩余秒数），不消耗 credit。

Inputs: no named parameters. Returns: result

tavily_researchA

Perform comprehensive research on a given topic or question. Use this tool when you need to gather information from multiple sources to answer a question. Returns a detailed response. Rate limit: 20 requests per minute. NOTE: this is an async task and may take 1-5 minutes.

Inputs: input (required), model, output_length, citation_format, +2 more. Returns: result

tavily_searchB

Search the web for current information on any topic. Use for news, facts, or data beyond your knowledge cutoff. Returns snippets and source URLs.

Inputs: query (required), topic, country, end_date, +11 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool serves a clear, distinct function: search for queries, extract for single URLs, crawl for site-wide content, map for URL discovery, research for multi-source synthesis, and pool_status for internal health. There is minimal overlap, and the descriptions clarify when to use each.

    Naming Consistency5/5

    All tools follow a consistent 'tavily_' prefix with lowercase snake_case verb/noun names. The naming pattern is predictable and clearly indicates the action (search, extract, crawl, map, research, pool_status), with no mixed conventions.

    Tool Count5/5

    With 6 tools, the server is well-scoped for a web research domain. Each tool adds distinct functionality, and the count is comfortably within the ideal range, neither sparse nor bloated.

    Completeness4/5

    The toolset covers the core web research lifecycle: search, extract, crawl, map, and comprehensive research. Minor gaps exist, such as advanced search parameters or bulk operations, but these are not essential for typical workflows. The inclusion of a pool status tool shows attention to operational needs.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • tavily-pool-mcp

      yanjin734-ltsm
      A
      license
      B
      quality
      D
      maintenance
      A local MCP server that exposes Tavily search as a tool and rotates across multiple API keys for reliability.
      1
      MIT

    • tavily-proxy-mcp

      pzehrel
      A
      license
      A
      quality
      C
      maintenance
      A proxy MCP server that connects to Tavily's official Streamable HTTP MCP, managing multiple API keys and automatically switching to the next one when the current key's quota is exhausted.
      5
      50 npm
      1
      MIT

    • tavily_mcp

      SqrtLeaves
      A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Tavily search and web data tools, enabling search, extract, crawl, and map operations through a simple HTTP or stdio interface.
      MIT