Tavily Search MCP

A cost-aware stdio MCP server for the official Tavily Search API.

Tool

tavily_search supports:

• Basic, Fast, and Ultra Fast Search at 1 API credit.
• Advanced Search at 2 API credits, only when explicitly selected.
• General, news, and finance topics.
• Domain and date filters.
• Up to 20 ranked results with source URLs and relevance scores.
• Reported credit usage, response time, and request ID.

The server always sends auto_parameters: false, include_usage: true, and excludes generated answers, raw pages, and images. This keeps cost and response size predictable while leaving synthesis to the MCP client.

Configuration

Required at call time:

TAVILY_API_KEY

On Windows, run npm run setup for the first-install configuration window. Enter multiple API keys separated by semicolons. It saves the API URL as a non-secret setting and stores the key array as a current-user DPAPI ciphertext under %APPDATA%\tavily-search-mcp\api-key.dpapi. Environment variables (TAVILY_API_KEYS or TAVILY_API_KEY) still take precedence for CI or temporary sessions.

Requests rotate across configured keys. Authentication, rate-limit, and quota responses (401, 429, 432, 433) can switch to the next distinct key, with a hard maximum of three attempts per MCP call. Server failures and ambiguous errors are not retried.

Optional:

TAVILY_API_URL=https://api.tavily.com/search

The server starts and lists tools without a key, then fails closed with a clear error if a search is attempted before TAVILY_API_KEY is configured. Secrets are never accepted as tool arguments or printed.

Each installation must use its own Tavily credentials. Do not share .env files, DPAPI ciphertext, setup screenshots, or API keys with other users.

Development

npm install
npm run check

Codex configuration

After building, register the compiled entry point and forward only the required environment variable:

[mcp_servers.tavily_search]
command = "node"
args = ["D:/path/to/tavily-search-mcp/dist/index.js"]
env_vars = ["TAVILY_API_KEYS", "TAVILY_API_KEY", "TAVILY_API_URL"]
startup_timeout_sec = 20
tool_timeout_sec = 60

No request is retried automatically. HTTP redirects are rejected so the API key cannot be forwarded to another origin.