Tavily MCP Load Balancer

v3.1.0 (2026-07-24)

• 低频配额队列：所有 /usage 请求统一排队、去重并遵守 Tavily 独立限流
• 双同步入口：支持同步过期 Key 和后台同步全部 Key
• 异步 Key 测试：勾选测试进入高优先级队列，成功后同时更新额度
• 额度显示修复：免费账户正确同步 1000 上限，未知额度不再显示为无限

v3.0.0 (2025-01-06)

• 官方 MCP 对齐：完整适配 tavily-mcp v0.2.12 工具参数与行为
• 智能错误处理：精细区分配额耗尽、速率限制与网络问题
• 持久化存储：SQLite 存储 API Key、配额与请求日志
• Web 管理后台：可视化管理 Key、统计、日志与设置
• 自动配额刷新：UTC 自然月自动更新配额状态

v2.2.0 (2025-08-15)

• 多架构镜像：linux/amd64 与 linux/arm64

v2.1.0 (2025-08-14)

• streamableHTTP 支持：HTTP POST /mcp 端点
• 多协议兼容：SSE + streamableHTTP

v2.0.0 (2025-08-12)

• 架构重构：原生 SSE 实现
• 工具更新：新增 tavily-crawl 和 tavily-map
• 安全改进：响应数据清理和字符编码处理

v1.0.0 (2025-08-05)

• 初始版本：多 API 密钥负载均衡

Docker Compose

git clone https://github.com/yatotm/tavily-mcp-loadbalancer.git
cd tavily-mcp-loadbalancer
cp .env.example .env
docker-compose up -d
docker-compose logs -f

自定义构建

docker build -t tavily-mcp-loadbalancer .
docker run -d --name tavily-mcp-lb -p 60002:60002 \
  -e TAVILY_API_KEYS="key1,key2" tavily-mcp-loadbalancer

开发模式

npm run start-gateway   # HTTP + UI
npm run dev             # MCP stdio
./start.sh              # 脚本启动

接口说明

streamableHTTP 示例

# 初始化
curl -X POST http://localhost:60002/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test-client", "version": "1.0.0"}
    }
  }'

# 获取工具列表
curl -X POST http://localhost:60002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# 调用搜索
curl -X POST http://localhost:60002/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search",
      "arguments": {"query": "OpenAI GPT-4", "max_results": 3}
    }
  }'

工具参数

search / tavily-search

{
  "query": "OpenAI GPT-4",
  "search_depth": "basic",
  "topic": "general",
  "max_results": 10,
  "country": "united states"
}

tavily-extract

{
  "urls": ["https://example.com/article"],
  "extract_depth": "basic",
  "format": "markdown"
}

tavily-crawl

{
  "url": "https://example.com",
  "max_depth": 2,
  "limit": 50,
  "extract_depth": "basic"
}

tavily-map

{
  "url": "https://example.com",
  "max_depth": 1,
  "limit": 50
}