# Tavily MCP Server

Tavily MCP Server is a Model Context Protocol (MCP) server that enables AI assistants like Claude to perform real-time web searches, extract content from URLs, crawl websites, and map site structures. It integrates with Claude Desktop, Cursor, Claude Code, and other MCP-compatible clients to provide AI agents with up-to-date information from the web.

The server exposes five core tools: `tavily_search` for web searches with customizable depth and filtering, `tavily_extract` for pulling content from specific URLs, `tavily_crawl` for systematically exploring websites, `tavily_map` for creating site structure maps, and `tavily_research` for comprehensive multi-source research tasks. All tools communicate with the Tavily API and require a Tavily API key for authentication.

## tavily_search

Performs real-time web searches with configurable depth, domain filtering, time-based filtering, and optional image results. Returns titles, URLs, content snippets, and relevance scores.

```typescript
// MCP Tool Call
{
  "name": "tavily_search",
  "arguments": {
    "query": "latest developments in quantum computing 2024",
    "search_depth": "advanced",
    "topic": "general",
    "time_range": "month",
    "max_results": 10,
    "include_images": true,
    "include_raw_content": false,
    "include_domains": ["arxiv.org", "nature.com"],
    "exclude_domains": ["wikipedia.org"],
    "country": "United States"
  }
}

// Response format
{
  "query": "latest developments in quantum computing 2024",
  "answer": "Recent quantum computing advances include...",
  "images": [
    { "url": "https://example.com/quantum.jpg", "description": "Quantum processor" }
  ],
  "results": [
    {
      "title": "Breakthrough in Quantum Error Correction",
      "url": "https://arxiv.org/abs/2024.12345",
      "content": "Researchers have achieved a significant milestone...",
      "score": 0.95,
      "published_date": "2024-01-15"
    }
  ]
}
```

## tavily_extract

Extracts and processes content from specified URLs with support for basic and advanced extraction modes. Advanced mode handles protected sites, tables, and embedded content.

```typescript
// MCP Tool Call
{
  "name": "tavily_extract",
  "arguments": {
    "urls": [
      "https://docs.example.com/api-reference",
      "https://blog.example.com/tutorial"
    ],
    "extract_depth": "advanced",
    "include_images": true,
    "format": "markdown",
    "include_favicon": true,
    "query": "authentication methods"
  }
}

// Response format
{
  "results": [
    {
      "url": "https://docs.example.com/api-reference",
      "content": "# API Reference\n\n## Authentication\n\nThe API supports...",
      "raw_content": "Full extracted content in markdown...",
      "favicon": "https://docs.example.com/favicon.ico"
    }
  ]
}
```

## tavily_crawl

Crawls websites starting from a root URL with configurable depth, breadth, and filtering options. Extracts content from multiple pages systematically.

```typescript
// MCP Tool Call
{
  "name": "tavily_crawl",
  "arguments": {
    "url": "https://docs.example.com",
    "max_depth": 2,
    "max_breadth": 10,
    "limit": 50,
    "instructions": "Focus on API documentation and code examples",
    "select_paths": ["/docs/.*", "/api/.*"],
    "select_domains": ["^docs\\.example\\.com$"],
    "allow_external": false,
    "extract_depth": "basic",
    "format": "markdown",
    "include_favicon": true
  }
}

// Response format
{
  "base_url": "https://docs.example.com",
  "results": [
    {
      "url": "https://docs.example.com/api/endpoints",
      "raw_content": "# API Endpoints\n\n## GET /users...",
      "favicon": "https://docs.example.com/favicon.ico"
    },
    {
      "url": "https://docs.example.com/docs/quickstart",
      "raw_content": "# Quick Start Guide\n\nThis guide will help you...",
      "favicon": "https://docs.example.com/favicon.ico"
    }
  ],
  "response_time": 2.45
}
```

## tavily_map

Creates a structured map of a website by analyzing its structure and navigation paths. Returns a list of discovered URLs without extracting content.

```typescript
// MCP Tool Call
{
  "name": "tavily_map",
  "arguments": {
    "url": "https://example.com",
    "max_depth": 3,
    "max_breadth": 20,
    "limit": 100,
    "instructions": "Map all product and documentation pages",
    "select_paths": ["/products/.*", "/docs/.*"],
    "select_domains": ["^example\\.com$", "^docs\\.example\\.com$"],
    "allow_external": false
  }
}

// Response format
{
  "base_url": "https://example.com",
  "results": [
    "https://example.com/products/item-1",
    "https://example.com/products/item-2",
    "https://example.com/docs/getting-started",
    "https://example.com/docs/api-reference",
    "https://docs.example.com/tutorials"
  ],
  "response_time": 1.23
}
```

## tavily_research

Performs comprehensive research on a topic by gathering and synthesizing information from multiple sources. Supports different research depths with automatic polling for results.

```typescript
// MCP Tool Call
{
  "name": "tavily_research",
  "arguments": {
    "input": "Analyze the current state of electric vehicle battery technology, including recent breakthroughs, major manufacturers, and future trends",
    "model": "pro"  // "mini" for narrow tasks, "pro" for broad research, "auto" for automatic selection
  }
}

// Response format (after polling completion)
{
  "content": "# Electric Vehicle Battery Technology Analysis\n\n## Current State\n\nThe EV battery market is dominated by lithium-ion technology...\n\n## Recent Breakthroughs\n\n1. Solid-state batteries: Toyota announced...\n2. Sodium-ion alternatives: CATL has developed...\n\n## Major Manufacturers\n\n- CATL (34% market share)\n- LG Energy Solution (14%)\n- BYD (12%)\n\n## Future Trends\n\n..."
}
```

## MCP Server Configuration

Configure the Tavily MCP server in your MCP client (Claude Desktop, Cursor, etc.) with environment variables for authentication and default parameters.

```json
// mcp.json or claude_desktop_config.json
{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "tvly-xxxxxxxxxxxxxxxxxxxxxxxxx",
        "DEFAULT_PARAMETERS": "{\"include_images\": true, \"max_results\": 10, \"search_depth\": \"advanced\"}"
      }
    }
  }
}

// Alternative: Remote MCP server (no local installation required)
{
  "mcpServers": {
    "tavily-remote-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-xxxxxxxxxx"],
      "env": {}
    }
  }
}
```

## Claude Code Integration

Add Tavily MCP to Claude Code CLI using the `claude mcp add` command for global or project-specific access.

```bash
# Add with API key in URL (project-specific)
claude mcp add --transport http tavily "https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-xxxxxxxxxx"

# Add globally (available across all projects)
claude mcp add --transport http --scope user tavily "https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-xxxxxxxxxx"

# Add with OAuth authentication flow (no API key in URL)
claude mcp add --transport http tavily https://mcp.tavily.com/mcp
# Then run `claude`, type `/mcp`, select Tavily, and complete OAuth

# List available tools
npx tavily-mcp --list-tools
```

## Summary

Tavily MCP Server is designed for AI agents that need real-time web access. Primary use cases include research tasks requiring current information beyond the AI's knowledge cutoff, content extraction from documentation sites, comprehensive website analysis through crawling and mapping, and multi-source research synthesis. The server handles rate limiting, authentication, and result formatting automatically.

Integration follows the standard MCP pattern: configure the server in your MCP client's configuration file with your Tavily API key, then tools become available to the AI assistant. The remote MCP option (`mcp.tavily.com`) eliminates local installation requirements, while the local NPX installation provides offline capability and customization through environment variables. Both support OAuth and API key authentication methods.