# Tavily Search MCP Server

A Model Context Protocol (MCP) server for the [Tavily Search API](https://tavily.com/) with automatic multi-key fallback. Built with FastMCP.

## Features

- 🔄 **Multi-key auto fallback** — automatically rotates through `TAVILY_API_KEY_1`, `TAVILY_API_KEY_2`, etc. when rate-limited
- 🌐 **Web search** — `tavily_search` for general web search
- 📄 **Content extraction** — `tavily_extract` to get content from URLs
- 🗺️ **Crawl & Map** — `tavily_crawl` / `tavily_map` for website structure
- 🔬 **Deep Research** — `tavily_research_create` / `tavily_research_get` for AI-powered research
- 📊 **Usage tracking** — `tavily_usage` to check API quota

## Quick Start

```json
{
  "mcpServers": {
    "tavily-search": {
      "command": "uvx",
      "args": ["tavily-search-mcp-server"]
    }
  }
}
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TAVILY_API_KEY_1` | Yes | Primary Tavily API key |
| `TAVILY_API_KEY_2..5` | No | Fallback keys for auto-rotation |

The server automatically discovers `TAVILY_API_KEY_*` env vars and falls back through them on 429 errors. Also supports single `TAVILY_API_KEY` for backward compatibility.

## Available Tools

| Tool | Description |
|------|-------------|
| `tavily_search` | Search the web with configurable depth, topic, time range |
| `tavily_extract` | Extract content from one or more URLs |
| `tavily_crawl` | Crawl a website with depth/breadth control |
| `tavily_map` | Map website structure |
| `tavily_search_context` | Search with raw content results |
| `tavily_research_create` | Create a deep research task |
| `tavily_research_get` | Get research task status/results |
| `tavily_usage` | Check API usage/quota |

## License

MIT