Tavily MCP Loadbalancer

v2.2.0 (2025-08-15)

• 🧬 Multi-architecture images: Released images for both linux/amd64 and linux/arm64 platforms; latest now points to 2.2.0.

v2.1.0 (2025-08-14)

• 🌐 streamableHTTP support: Added a new HTTP POST /mcp endpoint to support the direct MCP request-response mode.
• 🔄 Multi-protocol compatibility: Supports both SSE and streamableHTTP to meet the needs of different clients.
• 📝 Documentation update: Added usage instructions and examples for the streamableHTTP interface.

v2.0.0 (2025-08-12)

• 🔄 Architecture refactoring: Changed from relying on supergateway to a native SSE implementation.
• 🛠️ Toolset update: Synchronized with the latest Tavily MCP toolset, added tavily-crawl and tavily-map.
• 📊 Monitoring enhancement: Added detailed API key usage logs and polling status.
• 🔒 Security improvement: Enhanced response data cleaning and character encoding processing.
• 📝 Documentation rewrite: Completely rewrote the README and optimized the project structure.

v1.0.0 (2025-08-05)

• 🚀 Initial release: A Tavily MCP load balancer based on supergateway.
• 🔄 Load balancing: Implemented a multi-API key polling mechanism.
• 🛡️ Failover: Added the function to automatically disable invalid keys.

Docker Compose Deployment

# 1. Clone the project
git clone https://github.com/yatotm/tavily-mcp-loadbalancer.git
cd tavily-mcp-loadbalancer

# 2. Configure environment variables
cp .env.example .env
# Edit the .env file

# 3. Start the service
docker-compose up -d

# 4. View logs
docker-compose logs -f

Custom Docker Build

# Build the image
docker build -t tavily-mcp-loadbalancer .

# Run the container
docker run -d \
  --name tavily-mcp-lb \
  -p 60002:60002 \
  -e TAVILY_API_KEYS="your-key1,your-key2,your-key3" \
  tavily-mcp-loadbalancer

Development Mode

# Run in development mode (hot reload)
npm run dev

# Execute step by step
npm run build
npm run start-gateway

# Start using the script
./start.sh

Interface Description

SSE interface: http://localhost:60002/sse Message interface: http://localhost:60002/message streamableHTTP interface: http://localhost:60002/mcp Health check: http://localhost:60002/health

streamableHTTP Usage Example

# Initialize the connection
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"}
    }
  }'

# Get the tool list
curl -X POST http://localhost:60002/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Call the search tool
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
      }
    }
  }'

Detailed Tool Parameters

1. search / tavily-search - Web Search

{
  "name": "search",
  "arguments": {
    "query": "OpenAI GPT-4",
    "search_depth": "basic",
    "topic": "general",
    "max_results": 10,
    "start_date": "2024-01-01",
    "end_date": "2024-12-31",
    "country": "US",
    "include_favicon": false
  }
}

2. tavily-extract - Web Content Extraction

{
  "name": "tavily-extract",
  "arguments": {
    "urls": ["https://example.com/article"],
    "extract_depth": "basic",
    "format": "markdown",
    "include_favicon": false
  }
}

3. tavily-crawl - Website Crawler

{
  "name": "tavily-crawl",
  "arguments": {
    "url": "https://example.com",
    "max_depth": 2,
    "max_breadth": 20,
    "limit": 50,
    "instructions": "Focus on technical content",
    "select_paths": ["/docs", "/api"],
    "select_domains": ["example.com"],
    "allow_external": false,
    "categories": ["technology"],
    "extract_depth": "basic",
    "format": "markdown",
    "include_favicon": false
  }
}

4. tavily-map - Website Map Generation

{
  "name": "tavily-map",
  "arguments": {
    "url": "https://example.com",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "instructions": "Map the main structure",
    "select_paths": ["/"],
    "select_domains": ["example.com"],
    "allow_external": false,
    "categories": ["general"]
  }
}

Direct MCP Usage

# Use the MCP protocol directly (stdio)
node dist/index.js

Management Scripts

# Test the server connection status
./manage.sh stats

# Test all tool functions
./manage.sh test

# Batch test weather search (test all API keys)
./manage.sh weather

# Display help information
./manage.sh help

Node.js Test Scripts

# Test the server connection
node check_stats_direct.cjs

# Run tool tests
node test_tools_direct.cjs

# Batch weather search test
node test_weather_search.cjs

# Test SSE connection and data security
node test_sse_validation.cjs

Monitoring Output Examples

Server Status Check

✅ Connection successful
📊 Tavily MCP Load Balancer Status:
✅ Search function is normal
Search result length: 2847 characters

API Key Polling Logs

[INFO] Using API key: tvly-dev-T... (Key 1/10)
[INFO] API key tvly-dev-T... request successful
[INFO] Using API key: tvly-dev-Y... (Key 2/10)
[INFO] API key tvly-dev-Y... request successful

Docker Environment Variables

# Set environment variables when running Docker
docker run -e "TAVILY_API_KEYS=key1,key2,key3" \
           -e "SUPERGATEWAY_PORT=60002" \
           yatotm1994/tavily-mcp-loadbalancer:latest

Development Environment Configuration

# Development environment variables
export TAVILY_API_KEYS="tvly-dev-key1,tvly-dev-key2"
export SUPERGATEWAY_PORT=60002

# Or use the .env file
cp .env.example .env
# Edit the .env file

SSE Connection Test

Verify SSE connection and data security:

# Run the SSE connection test
node test_sse_validation.cjs

Test contents:

• ✅ SSE connection establishment and session management
• ✅ JSON-RPC message sending and receiving
• ✅ Response data security verification
• ✅ Control character and special character processing
• ✅ Large data response processing
• ✅ Error handling and logging

Local Running Issues

1. No available API keys

   • Check the environment variable: echo $TAVILY_API_KEYS
   • Ensure the key format is correct (starts with tvly-)
   • Use node check_stats_direct.cjs to test the connection

2. API key error or disabled

   • Check the error information in the server logs
   • Use ./manage.sh weather to batch test all keys
   • Check if the key quota is used up

3. Connection timeout or network issues

   • Check network connection and firewall settings
   • Confirm if the Tavily API service is normal
   • Try reducing the number of concurrent requests

4. SSE connection issues

   • Use node test_sse_validation.cjs to test the SSE connection
   • Check if port 60002 is occupied: lsof -i :60002
   • Confirm that the server has started normally

Docker-related Issues

Docker Debugging Commands

# View container logs
docker logs -f tavily-mcp-lb

# Enter the container for debugging
docker exec -it tavily-mcp-lb sh

# Check environment variables
docker exec tavily-mcp-lb env | grep TAVILY