Tavily MCP Server

The Tavily MCP server provides search, extract, map, and crawl tools for real-time web search, intelligent data extraction from web pages, structured website mapping, and systematic website exploration.

Helpful Resources

Remote MCP Server

Connect directly to Tavily's remote MCP server without requiring local installation or configuration.

Use the remote MCP server URL with your Tavily API key:

https://mcp.tavily.com/mcp/?tavilyApiKey=

Get your Tavily API key from tavily.com.

Alternatively, pass your API key through an Authorization header if your MCP client supports it:

Authorization: Bearer

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 with your desired defaults:

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

Connect to Claude Code

Claude Code is Anthropic's official CLI tool for Claude. Add the Tavily MCP server using the claude mcp add command with one of two authentication methods.

Option 1: API Key in URL

Pass your API key directly in the URL. Replace <your-api-key> with your actual Tavily API key:

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

Option 2: OAuth Authentication Flow

Add the server without an API key in the URL:

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

After adding, complete the authentication flow:

Run claude to start Claude Code
Type /mcp to open the MCP server management
Select the Tavily server and complete the authentication process

Global Availability

Add --scope user to either command to make the Tavily MCP server available globally across all your projects:

claude mcp add --transport http --scope user tavily https://mcp.tavily.com/mcp/?tavilyApiKey=

Once configured, you'll have access to the Tavily search, extract, map, and crawl tools.

Connect to Cursor

Click the Add to Cursor button to install the MCP server. You will need to edit the configuration to add your API key. Get a Tavily API key from tavily.com.

Step 1

Click the install button.

Step 2

The MCP should now be installed. If the blue toggle is not already enabled, turn it on manually. Edit the configuration to include your Tavily API key.

Step 3

You will be redirected to your mcp.json file where you need to add your API key:

{ "mcpServers": { "tavily-remote-mcp": { "command": "npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>", "env": {} } } } ## Remote MCP Server OAuth Flow The Tavily Remote MCP server supports secure OAuth authentication for seamless connection and authorization with compatible clients. ### Using MCP Inspector Open the MCP Inspector and click "Open Auth Settings". Select the OAuth flow and complete these steps: 1. Metadata discovery 2. Client registration 3. Preparing authorization 4. Request authorization and obtain the authorization code 5. Token request 6. Authentication complete Once finished, you will receive an access token for secure authenticated requests to the Tavily Remote MCP server. ### Using Other MCP Clients Configure your MCP client to use OAuth without including your Tavily API key in the URL. For example, in your `mcp.json`: ```json { "mcpServers": { "tavily-remote-mcp": { "command": "npx mcp-remote https://mcp.tavily.com/mcp", "env": {} } } } To clear stored OAuth credentials and reauthenticate, run: rm -rf ~/.mcp-auth ### Authentication Notes OAuth authentication is optional. You can still use API key authentication at any time by including your Tavily API key in the URL query parameter (`?tavilyApiKey=...`) or by setting it in the `Authorization` header. ### Selecting Which API Key Is Used for OAuth After successful OAuth authentication, control which API key is used by naming it `mcp_auth_default`: - If you set a key named `mcp_auth_default` in your personal account, that key will be used for the auth flow. - If you are part of a team that has a key named `mcp_auth_default`, that key will be used for the auth flow. - If you have both a personal key and a team key named `mcp_auth_default`, the personal key will be prioritized. - If no `mcp_auth_default` key is set, the `default` key in your personal account will be used. If no `default` key is set, the first available key will be used. ## Local MCP ### Prerequisites Before you begin, ensure you have: - [Tavily API key](https://app.tavily.com/home) — sign up for a free account if needed - [Claude Desktop](https://claude.ai/download) or [Cursor](https://cursor.sh) - [Node.js](https://nodejs.org/) v20 or higher — verify with `node --version` - [Git](https://git-scm.com/downloads) (only needed if using Git installation method) - macOS: `brew install git` - Linux Debian/Ubuntu: `sudo apt install git` - Linux RedHat/CentOS: `sudo yum install git` - Windows: Download [Git for Windows](https://git-scm.com/download/win) ### Running with NPX npx -y tavily-mcp@latest ## Default Parameters Configuration Set default parameter values for the `tavily-search` tool using the `DEFAULT_PARAMETERS` environment variable. This allows you to configure default search behavior without specifying these parameters in every request. ### Example Configuration export DEFAULT_PARAMETERS='{"include_images": true}' ### Example Usage from Client ```json { "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\"}" } } } } ## Identifying the End User Optionally identify the end user on whose behalf requests are being made by setting the `TAVILY_HUMAN_ID` environment variable. When set, Tavily MCP forwards it as the `X-Human-Id` header on every API call, enabling per-user analytics. This is entirely optional — leave it unset and behavior is unchanged. ```json { "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 `human_id` server-side (SHA-256) before storage, so the raw value is never persisted. Prefer opaque identifiers (such as an internal user ID) over raw PII like emails when possible.