MultiTavilyKey 🗝️

Zero-dependency Tavily API proxy with automatic key rotation.

Tavily's free tier gives 1,000 searches/month per API key. MultiTavilyKey lets you pool multiple keys — when one hits the rate limit (429), it automatically rotates to the next. Your tools keep working, no interruption.

Works with any MCP-compatible client: Hermes Agent, Codex CLI, Claude Desktop, Cursor, Windsurf, and any tool that can register an MCP server or call api.tavily.com.

How it works

Your MCP client (Hermes / Codex / Claude / …)
  └─→ localhost:8765 (MultiTavilyKey)
        ├─ TAVILY_API_KEY      (primary)    → 200 → return
        ├─ TAVILY_API_KEY_BACKUP1            → 429 → try next
        ├─ TAVILY_API_KEY_BACKUP2            → 429 → try next
        ├─ TAVILY_API_KEY_BACKUP3            → 429 → try next
        └─ All exhausted                     → clear error

The proxy serves two interfaces on the same port:

• MCP SSE endpoint (GET /mcp + POST /mcp/message) — implements the Model Context Protocol, exposing tavily_search, tavily_extract, tavily_research, tavily_crawl, and tavily_map
• REST API proxy (/*) — forwards any POST to api.tavily.com/{path} with key rotation

Quick start

1. Set up keys

git clone https://github.com/lunkerchen/MultiTavilyKey.git
cd MultiTavilyKey

# Create .env with your Tavily API keys:
echo 'TAVILY_API_KEY=tvly-your-primary-key' >> .env
echo 'TAVILY_API_KEY_BACKUP1=tvly-backup-1' >> .env
echo 'TAVILY_API_KEY_BACKUP2=tvly-backup-2' >> .env
echo 'TAVILY_API_KEY_BACKUP3=tvly-backup-3' >> .env

2. Start the proxy

python3 tavily-proxy.py

Or use the wrapper that loads from .env:

bash tavily-proxy.sh

Health check:

curl http://127.0.0.1:8765/health
# → {"status":"ok","keys_total":4,"service":"MultiTavilyKey"}

3. Register with your MCP client

Hermes Agent:

hermes mcp add tavily --url "http://localhost:8765/mcp"
hermes gateway restart

Codex CLI:

codex mcp add tavily --url "http://localhost:8765/mcp"

Claude Desktop:

// claude_desktop_config.json
{
  "mcpServers": {
    "tavily": {
      "url": "http://localhost:8765/mcp"
    }
  }
}

Cursor / Windsurf:

Add as an MCP server with URL http://localhost:8765/mcp.

macOS auto-start (launchd)

# Edit paths in the plist, then:
cp com.multitavilykey.proxy.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.multitavilykey.proxy.plist

Or run the installer:

bash install.sh

The proxy starts at login, stays alive, and logs to mtk.log.

Windows setup

Prerequisites

• Python 3.11+ — install with "Add Python to PATH" checked
• Git for Windows (git-scm.com) or clone via any Git client

1. Set up keys

git clone https://github.com/lunkerchen/MultiTavilyKey.git
cd MultiTavilyKey

# Create .env with your Tavily API keys:
echo 'TAVILY_API_KEY=tvly-your-primary-key' >> .env
echo 'TAVILY_API_KEY_BACKUP1=tvly-backup-1' >> .env
echo 'TAVILY_API_KEY_BACKUP2=tvly-backup-2' >> .env
echo 'TAVILY_API_KEY_BACKUP3=tvly-backup-3' >> .env

2. Start the proxy

python tavily-proxy.py

Health check (in a new terminal):

curl http://127.0.0.1:8765/health

3. Auto-start with Task Scheduler

Create a task that runs python tavily-proxy.py from the project directory at user login:

# One-liner to create a scheduled task
$action = New-ScheduledTaskAction -Execute "python" -Argument "tavily-proxy.py" -WorkingDirectory "$HOME\MultiTavilyKey"
$trigger = New-ScheduledTaskTrigger -AtLogOn
Register-ScheduledTask -TaskName "MultiTavilyKey" -Action $action -Trigger $trigger -RunLevel Limited -Force

Or use NSSM (Non-Sucking Service Manager) to run it as a Windows Service:

nssm install MultiTavilyKey "C:\path\to\python.exe" "C:\path\to\MultiTavilyKey\tavily-proxy.py"
nssm set MultiTavilyKey AppDirectory "C:\path\to\MultiTavilyKey"
nssm start MultiTavilyKey

Logs are written to mtk.log in the project directory.

WSL alternative (recommended)

If you use WSL2, follow the Linux instructions — performance and reliability are better than native Windows for this kind of background proxy.

Options

Flag	Env var	Default	Description
--host	MTK_HOST	127.0.0.1	Bind address
--port	MTK_PORT	8765	Bind port
--log-level	—	INFO	DEBUG, INFO, WARNING, ERROR

Environment variables

Variable	Required	Purpose
TAVILY_API_KEY	✅	Primary Tavily API key
TAVILY_API_KEY_BACKUP1	❌	First backup key
TAVILY_API_KEY_BACKUP2	❌	Second backup key
TAVILY_API_KEY_BACKUP3	❌	Third backup key
MTK_HOST	❌	Override bind host
MTK_PORT	❌	Override bind port
MTK_ENV_FILE	❌	Path to .env for the wrapper script

Rotation behavior

• On HTTP 429 (rate limit / quota exceeded) or 402 (insufficient credits) → automatically retries the next key
• Retries are instant (< 100ms overhead per retry)
• On other HTTP errors (4xx, 5xx) → fails immediately (not a quota issue)
• When all keys are exhausted → returns a clear error message
• Keys are tried in order: TAVILY_API_KEY → BACKUP1 → BACKUP2 → BACKUP3

The 5 Tavily tools

Tool	Purpose
tavily_search	Web search with depth/domain/time/country control
tavily_extract	URL content extraction in clean text
tavily_research	Multi-source deep research and synthesis
tavily_crawl	Website crawling for page structure
tavily_map	Site structure exploration

Why not just…?

• … use an API gateway? MultiTavilyKey is a single Python file with zero dependencies (stdlib only). No npm install, no Docker, no config file parsing.
• … use one key? Tavily free tier is 1,000/month. Four keys = 4,000/month, and rotation is transparent.
• … write a cron to swap keys? Cron has a delay between "key exhausted" and "key swapped". MultiTavilyKey retries in milliseconds.

Requirements

• Python 3.11+ (stdlib only — no pip install needed)
• macOS, Linux, or WSL

License

MIT