简体中文 | [English](README_EN.md)

# tavily-rotator-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org)

本地 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 传输，被宿主进程拉起，不监听端口

## 安装

需要 [uv](https://docs.astral.sh/uv/)（它会顺带帮你管理 Python，本机无需预装）：

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

## 配置 key

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

```bash
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 一样直观）**

```json
{
  "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 配置）：**

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

**Claude Code（CLI）：**

```bash
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 |

## 更新 / 卸载

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

## 注意

- key 仅用于向 Tavily API 发送 `Authorization` 请求头，不会被记录或发送到其他任何地方
- 通过轮换器使用多个免费账号会放大免费额度——这处于 Tavily 服务条款的灰色地带，个人轻度使用无妨，别拿它做商业用途

## 许可证

[MIT](LICENSE)