unlimited-tavily-mcp

A local Model Context Protocol server that fronts the official Tavily remote MCP and spreads your tool calls across multiple API keys.

One Tavily key hits its rate limit? The proxy moves to the next one, transparently.

How it works

• Round-robin — each call goes to the next ready key in the pool.

• Rate-limited keys (429/432) enter a cooldown and rejoin automatically. 432 is Tavily's plan usage-limit status (This request exceeds your plan's set usage limit) — it is treated like a rate limit because other keys in the pool usually still have quota. A Retry-After header from Tavily is honored when present.

• Invalid keys (401/403) are disabled for the lifetime of the process.

• No blind retries — ambiguous network and server errors are returned as-is so paid operations (search, extract, crawl) are never duplicated.

• Live key reload — add a key to the keys file while the server runs; it joins the pool without a restart. Keys are identified only by a short SHA-256 fingerprint; they are never logged.

• Full tool pass-through — tavily_search, tavily_extract, tavily_crawl, tavily_map, tavily_research, including progress notifications for long research calls.

Related MCP server: tavily-proxy-mcp

Requirements

• Bun — it runs the TypeScript source directly, no build step needed.

• One or more Tavily API keys.

Setup

git clone https://github.com/d1alect-tech/unlimited-tavily-mcp.git
cd unlimited-tavily-mcp
bun install

Create the keys file (default location: ~/.config/opencode/secrets/tavily.keys):

mkdir -p ~/.config/opencode/secrets
cp tavily.keys.example ~/.config/opencode/secrets/tavily.keys

Put one key per line. Blank lines and # comments are ignored. Duplicates are dropped.

Use with OpenCode

Add the block from opencode.example.jsonc to your opencode.jsonc, pointing the second command argument at your checkout:

"mcp": {
  "tavily": {
    "type": "local",
    "command": ["bun", "/absolute/path/to/unlimited-tavily-mcp/src/index.ts"],
    "enabled": true,
    "timeout": 970000
  }
}

Configuration

Run standalone (speaks MCP over stdio, so any MCP client works):

bun src/index.ts

Development

bun run test   # type-checks and runs the node:test suite (30 tests)

Security

Keys are read from a file outside the repo and never appear in logs — a tvly-* redactor guards every error path. See SECURITY.md.

License

MIT