Tavily MCP Server

The Tavily MCP server provides several tools for web-based intelligence via the Model Context Protocol:

• tavily-search: Real-time web search capabilities.
• tavily-extract: Intelligent data extraction from web pages.
• tavily-map: Creates a structured map of a website.
• tavily-crawl: Systematically explores websites via a web crawler.

To connect to Cursor, you can use the automated installer or manual configuration in your mcp.json file.

Manual Configuration: Add the following to your mcp.json file, replacing <your-api-key> with your actual Tavily API key:

{
  "mcpServers": {
    "tavily-remote-mcp": {
      "command": "npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>",
      "env": {}
    }
  }
}

Using OAuth in Cursor: To use OAuth instead of an API key in the URL, configure your mcp.json like this:

{
  "mcpServers": {
    "tavily-remote-mcp": {
      "command": "npx mcp-remote https://mcp.tavily.com/mcp",
      "env": {}
    }
  }
}

Clearing Credentials: If you need to clear stored OAuth credentials and reauthenticate, run: rm -rf ~/.mcp-auth

You can add the Tavily MCP server to Anthropic's Claude Code CLI using the claude mcp add command.

Option 1: API Key in URL

claude mcp add --transport http tavily https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>

Option 2: OAuth Authentication

1. Add the server without a key in the URL:

claude mcp add --transport http tavily https://mcp.tavily.com/mcp

2. Run claude to start the CLI.
3. Type /mcp to open management.
4. Select the Tavily server and follow the authentication prompts.

Tip: Use the --scope user flag to make the server available globally across all projects:

claude mcp add --transport http --scope user tavily https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>

Instead of running the server locally, you can connect directly to Tavily's remote MCP server. This removes the need for local installation.

Authentication via URL: Use the remote MCP server URL with your Tavily API key as a query parameter: https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>

Authentication via Header: If your MCP client supports it, you can pass your API key in the Authorization header: Authorization: Bearer <your-api-key>

Setting Default Parameters: When using the remote MCP, you can specify default parameters for all requests by including a DEFAULT_PARAMETERS header containing a JSON object.

{
  "include_images": true, 
  "search_depth": "basic", 
  "max_results": 10
}

To run the Tavily MCP server locally, ensure you have Node.js (v20 or higher) installed. You can run the server immediately using npx:

npx -y tavily-mcp@latest

To enable per-user analytics, you can optionally identify the end user by setting the TAVILY_HUMAN_ID environment variable. When set, Tavily MCP forwards this value as the X-Human-Id header on every API call.

Configuration Example:

{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here",
        "TAVILY_HUMAN_ID": "your-user-id"
      }
    }
  }
}

Privacy Note: Tavily hashes the human_id server-side using SHA-256 before storage. It is recommended to use opaque identifiers (like internal user IDs) rather than PII (like emails).

You can set default parameter values for the tavily-search tool using the DEFAULT_PARAMETERS environment variable. This allows you to configure default search behavior (like include_images or search_depth) without specifying them in every request.

Example via Shell Export:

export DEFAULT_PARAMETERS='{"include_images": true}'

Example via MCP Client Configuration (e.g., Claude Desktop): In your client's configuration file, include the DEFAULT_PARAMETERS key within the env object. Note that the JSON string must be properly escaped.

{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here",
        "DEFAULT_PARAMETERS": "{\"include_images\": true, \"max_results\": 15, \"search_depth\": \"advanced\"}"
      }
    }
  }
}

The Tavily MCP server uses environment variables for authentication and behavior configuration:

• TAVILY_API_KEY: Your Tavily API key. If not provided, the server runs in keyless mode. In keyless mode, tavily_search and tavily_extract are available, but other tools will return a message stating an API key is required.
• TAVILY_HUMAN_ID: An optional ID to identify human usage.
• DEFAULT_PARAMETERS: A JSON string containing default values for tool parameters. This allows you to pre-configure settings like search depth or result limits.

Example DEFAULT_PARAMETERS format:

{"search_depth":"basic","include_images":true}

Map a website's structure. Returns a list of URLs found starting from the base URL.

Key Parameters:

• url (string, required): The root URL to begin mapping.
• max_depth (integer): Max depth of the mapping. Default is 1.
• max_breadth (integer): Max links to follow per page. Default is 20.
• limit (integer): Total links to process. Default is 50.
• instructions (string): Natural language instructions for the crawler.
• select_paths (array of strings): Regex patterns for path selection.
• select_domains (array of strings): Regex patterns for domain restriction.

Perform comprehensive research on a topic. Gathers information from multiple sources to answer complex questions. Rate limit: 20 requests per minute.

Key Parameters:

• input (string, required): A comprehensive description of the research task.
• model (enum: mini, pro, auto):
  • mini: Good for narrow tasks with few subtopics.
  • pro: Good for broad tasks with many subtopics.
  • auto: Automatically selects the best model.

Note: This tool uses a polling mechanism or streaming to handle long-running research tasks.

Extract content from specific URLs. Returns raw page content in markdown or text format.

Key Parameters:

• urls (array of strings, required): List of URLs to extract.
• extract_depth (enum: basic, advanced): Use advanced for LinkedIn, protected sites, or tables/embedded content.
• format (enum: markdown, text): Output format. Default is markdown.
• query (string): A query used to rerank content chunks by relevance.
• include_images (boolean): Include images from pages.
• include_favicon (boolean): Include favicon URLs.