Skip to main content
Glama
yatotm

Tavily MCP Load Balancer

by yatotm
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Tavily MCP Load Balancer

Docker Hub Docker Image Size License: MIT

Language / 语言: English | 中文

一个支持多 API 密钥负载均衡的 Tavily MCP 服务器，提供 SSE 和 streamableHTTP 接口，自动轮询多个 API 密钥以实现高可用性。

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 密钥负载均衡

功能特性

  • 智能负载均衡 — 轮询 + 权重调度，多 Key 高可用

  • 错误分级处理 — 速率限制 / 配额耗尽 / 鉴权错误精确识别

  • 多协议支持 — MCP stdio / SSE / streamableHTTP 全覆盖

  • 数据持久化 — SQLite 存储 Key、配额与日志

  • Web 管理后台 — Dashboard、Key 管理、统计、日志、设置

  • 实时更新 — WebSocket 推送统计刷新

  • 数据安全 — Key 加密存储 + 脱敏展示

Related MCP server: tavily-pool-mcp

快速开始

Docker 部署（推荐）

docker run -d \
  --name tavily-mcp-lb \
  -p 60002:60002 \
  -e DATABASE_ENCRYPTION_KEY="your-32-byte-random-key" \
  -e ADMIN_PASSWORD="optional-admin-password" \
  -e TAVILY_API_KEYS="your-key1,your-key2,your-key3" \
  yatotm1994/tavily-mcp-loadbalancer:latest

镜像支持 amd64 / arm64，Docker 会自动匹配本机架构。

本地开发

# 1. 克隆并安装
git clone https://github.com/yatotm/tavily-mcp-loadbalancer.git
cd tavily-mcp-loadbalancer
npm install

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env，设置 DATABASE_ENCRYPTION_KEY（必填）与 ADMIN_PASSWORD（可选）

# 3. 启动服务
npm run build-and-start

服务启动后访问：

端点

地址

管理后台

http://localhost:60002

SSE 接口

http://localhost:60002/sse

streamableHTTP

http://localhost:60002/mcp

API

http://localhost:60002/api

WebSocket

ws://localhost:60002/ws

首次启动后在管理后台添加 API Key。环境变量 TAVILY_API_KEYS 仅用于初始导入。

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              # 脚本启动

可用工具

工具名称

功能描述

主要参数

search / tavily-search

网络搜索

query, max_results, search_depth

tavily-extract

网页内容提取

urls, extract_depth, format

tavily-crawl

网站爬虫

url, max_depth, limit

tavily-map

网站地图生成

url, max_depth, max_breadth

接口说明

接口

地址

SSE

http://localhost:60002/sse

消息

http://localhost:60002/message

streamableHTTP

http://localhost:60002/mcp

健康检查

http://localhost:60002/health

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
}

配置

环境变量

变量名

描述

默认值

PORT

服务端口

60002

HOST

绑定地址

0.0.0.0

DATABASE_PATH

数据库路径

./data/tavily.db

DATABASE_ENCRYPTION_KEY

加密密钥（必填）

-

ADMIN_PASSWORD

管理后台密码

-

ENABLE_WEB_UI

启用 Web UI

true

MAX_CONCURRENT_REQUESTS

最大并发

4

REQUEST_TIMEOUT

请求超时（ms）

30000

MAX_KEY_ERRORS

Key 最大错误次数

5

USAGE_SYNC_MIN_INTERVAL_MS

/usage 队列请求最小间隔（ms）

75000

USAGE_SYNC_RETRY_DELAY_MS

上游未返回 retry-after 时的全局冷却（ms）

600000

USAGE_SYNC_STALE_AFTER_MS

配额数据过期时间（ms）

21600000

USAGE_SYNC_SCHEDULE_INTERVAL_MS

自动扫描过期 Key 的间隔（ms）

21600000

LOG_RETENTION_DAYS

日志保留天数

30

LOG_LEVEL

日志级别

info

TAVILY_API_KEYS

初始 Key（逗号分隔）

-

配置示例

# .env
PORT=60002
DATABASE_ENCRYPTION_KEY=your-32-byte-random-key
ADMIN_PASSWORD=optional-password
TAVILY_API_KEYS=tvly-key1,tvly-key2

故障排除

问题

解决方案

无可用 API 密钥

在管理后台检查 Key 状态和配额

连接超时

检查网络和防火墙设置

端口被占用

lsof -i :60002 检查端口占用

# 健康检查
curl http://localhost:60002/health

# 查看日志
docker logs tavily-mcp-lb

建议在 Web 管理后台查看请求统计、错误日志与 Key 状态。

许可证

MIT License

如果这个项目对你有帮助，欢迎 Star ⭐

Install Server
A
license - permissive license
B
quality
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Related MCP Servers

  • MCP Nexus - Cloudflare Workers

    ykq007
    F
    license
    -
    quality
    -
    maintenance
    A unified MCP server for Tavily and Brave Search APIs that features automatic API key rotation and zero-cost hosting on Cloudflare Workers. It provides tools for web searching, data extraction, and research with secure, encrypted key management.

  • 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-mcp-proxy

    welyfun
    A
    license
    -
    quality
    B
    maintenance
    A proxy MCP server for Tavily search and extract APIs with support for multiple API keys, random rotation, and bearer token authentication.
    MIT

  • tavily-proxy-mcp

    pzehrel
    A
    license
    A
    quality
    A
    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
    17
    1
    MIT

View all related MCP servers

Related MCP Connectors

  • ATEX AI Gateway

    One API key for 6 AI models. Pay-per-use. MCP protocol support with web search.

  • TokenOracle

    Hosted MCP server for LLM cost estimation, model comparison, and budget-aware routing.

  • mcp

    MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.

View all MCP Connectors

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yatotm/tavily-mcp-loadbalancer'

If you have feedback or need assistance with the MCP directory API, please join our Discord server