Skip to main content
Glama
IamPa

tavily-pool-gateway

by IamPa
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Tavily Pool Gateway

EN | 中文

Pool multiple Tavily API keys behind one endpoint. Automatic rotation, circuit breaking, and credit accounting — when one account's monthly quota runs out, the next key takes over seamlessly. Ships with a web console and a Tauri desktop app.

screenshot

这是什么

一个可以把多个Tavily账号的api转换为一个地址的项目。Tavily Pool Gateway 把你手上的多个 Tavily 账号 key 池化成一个服务：

  • 一个地址接入：HTTP（兼容 Tavily 官方 API，SDK 改个 base_url 就能用）或 MCP（AI 客户端直接连）

  • 自动轮询：额度最多的 key 优先；某个账号用完自动切换下一个，跨月自动恢复

  • 熔断保护：连续限流自动冷却、无效 key 自动禁用、403 风控自动恢复

  • 精确记账：每次请求从响应读取真实消耗，每小时与官方 /usage 校准

  • Web 控制台 + 桌面应用：浏览器打开 /ui/ 或用 Tauri 壳，监控额度、测试搜索、添加 key

Related MCP server: tavily-proxy

核心特性

能力

说明

多 key 池化

逗号分隔或 api.txt 每行一个，运行时热添加（自动持久化 + 立即校准额度）

端点兼容

/v1/search /v1/extract /v1/crawl /v1/map /v1/research，与官方 API 同构

MCP Server

/mcp/（streamable-http），7 个工具：tavily_search / tavily_extract / tavily_crawl / tavily_map / tavily_research / tavily_get_research / tavily_pool_status

安全防护

自动剥离请求体中的 api_key（防止客户端误配置覆盖池内 key 导致全池熔断）

异步研究

research 任务透传（201 创建 / 202 轮询 / 200 完成），网关维护任务与 key 的映射

轻量

单进程 Python，运行内存约 60–100MB，无数据库

快速开始

1. 启动网关

git clone https://github.com/YOUR_NAME/tavily-pool-gateway.git
cd tavily-pool-gateway

python -m venv .venv
.venv/bin/pip install -r requirements.txt        # Windows: .venv\Scripts\pip install -r requirements.txt

# 配置 key（二选一）
echo "tvly-your-key-1" >> api.txt                 # 方式 A：api.txt 每行一个
# TAVILY_KEYS=tvly-key-1,tvly-key-2               # 方式 B：环境变量逗号分隔

.venv/bin/python -m uvicorn app:app --host 0.0.0.0 --port 8000

打开 http://localhost:8000/ui/ 即是控制台。

没有 key？到 tavily.com 免费注册，每账号每月 1000 credits。

2. 接入

HTTP（SDK 兼容）：

from tavily import TavilyClient
client = TavilyClient(api_key="any", base_url="http://localhost:8000/v1")
client.search("hello")

MCP（AI 客户端）：在支持 MCP 的客户端（Codex / Hermes / Cursor 等）添加：

http://localhost:8000/mcp/

3. 桌面应用（可选）

cd desktop/src-tauri
npx @tauri-apps/cli build

安装包输出在 target/release/bundle/。桌面壳启动时自动探测网关（默认 http://127.0.0.1:8000，可用环境变量 TAVILY_GATEWAY_URL 指定远程地址）；未启动时显示连接指导页。

也可以直接从 Releases 下载安装包（GitHub Actions 在打 tag 时自动构建 Windows / macOS / Linux 三平台）。

部署到服务器（systemd）

# 服务器上
sudo cp deploy/tavily-juhe.service /etc/systemd/system/
# 按需修改单元内的 WorkingDirectory / ExecStart / --host（建议绑定内网网卡 IP，勿用 0.0.0.0 暴露公网）
sudo systemctl daemon-reload && sudo systemctl enable --now tavily-juhe

API 摘要

方法

路径

说明

POST

/v1/search /v1/extract /v1/crawl /v1/map

与 Tavily 官方 API 同构，key 由网关注入

POST

/v1/research

创建深度研究任务（异步）

GET

/v1/research/{request_id}

查询任务状态（202 进行中 / 200 完成）

GET

/v1/usage /admin/pool

key 池额度与状态（零 credits 消耗）

POST

/admin/keys

热添加 key：{"keys": ["tvly-..."]}

GET

/health

存活检查

GET

/ui/

Web 控制台

POST

/mcp/

MCP streamable-http 入口

架构

调用方（SDK / MCP 客户端 / Web 控制台）
        │
        ▼
┌─────────────────────────────────────┐
│  Gateway (FastAPI, 单进程)           │
│  ├─ gateway.py   HTTP 路由 /v1 /admin│
│  ├─ mcp_server.py MCP 工具 (7 个)    │
│  ├─ keypool.py   key 池核心          │
│  │   ├─ 状态机 healthy/cooling/     │
│  │   │          exhausted/disabled  │
│  │   ├─ 选 key：剩余额度优先          │
│  │   ├─ 记账：usage.credits + 校准   │
│  │   └─ 防护：剥离 body api_key      │
│  └─ webui/       Web 控制台          │
└─────────────────────────────────────┘
        │  轮询转发（Authorization: Bearer）
        ▼
  Tavily 官方 API（多账号）

注意事项

  • 鉴权：默认无鉴权，设计为跑在可信内网（如 Tailscale）。如需暴露，设置环境变量 GATEWAY_TOKEN，调用方带 Authorization: Bearer <token>。

  • 合规：请聚合自己真实持有的账号。批量注册免费账号薅额度有封号风险。

  • api.txt 含真实 key，已在 .gitignore 中，请勿提交或分享。

  • 本项目全为vibecoding，属于个人使用分享，可能体验等各个方面都有问题或bug，还望海涵。

License

MIT

This server cannot be deployed

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

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

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

    sunwu51
    F
    license
    Not graded
    quality
    D
    maintenance
    A Cloudflare Worker that proxies requests to the Tavily API with automatic key rotation from a pool, providing search, extract, crawl, and map tools via MCP.
    23
    -

  • tavily-proxy

    Tokisaki-Galaxy
    F
    license
    Not graded
    quality
    D
    maintenance
    A Cloudflare Worker that proxies the Tavily API through MCP, offering search, extract, crawl, and map tools with automatic API key rotation and health-based routing.
    3
    -