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.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-search-mcp-server

快速开始

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

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
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Looking for Admin?

Admins can modify the Dockerfile, update the server description, and track usage metrics. If you are the server author, to access the admin panel.

Tools

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