Tavily MCP Server

Connect to Tavily using MCP in one click.

MCP server URL

https://mcp.tavily.com/mcp/

Paste the server URL into any MCP client, and sign in to Tavily when your client prompts you. Or pick your client below:

Claude & Claude Code
ChatGPT & Codex
Cursor
VS Code
Other clients

Claude Code

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

Claude (claude.ai, Claude Desktop, and Cowork): click Add to Claude, then Connect, and sign in to Tavily. Claude Code: run the command above, then start a new session to sign in. See Connect to Claude Code and the Claude guide for more options.

Codex

codex mcp add tavily --url https://mcp.tavily.com/mcp/
codex mcp login tavily

Click Add to ChatGPT and Codex to open the Tavily plugin, then connect it and sign in to Tavily. To use the MCP server in Codex instead, run the commands above.

mcp.json

{
  "mcpServers": {
    "tavily": {
      "url": "https://mcp.tavily.com/mcp/"
    }
  }
}

Click Add to Cursor and sign in to Tavily when Cursor prompts you, or add the server to ~/.cursor/mcp.json yourself. See Connect to Cursor to use an API key instead.

Terminal

code --add-mcp '{"name":"tavily","type":"http","url":"https://mcp.tavily.com/mcp/"}'

Click Add to VS Code or run the command above, then start the server from the MCP Servers list and sign in to Tavily.

{
  "mcpServers": {
    "tavily": {
      "url": "https://mcp.tavily.com/mcp/"
    }
  }
}

{
  "mcpServers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.tavily.com/mcp/"]
    }
  }
}

Use Remote (HTTP) if your client supports remote MCP servers. Otherwise, use the Local bridge, which connects stdio-only clients to the remote server through mcp-remote.

No account yet? Keyless access lets you call Search and Extract with no API key.

What you get

The Tavily MCP server gives your agent these tools:

Tool	What it does
`tavily_search`	Search the web for current, relevant sources.
`tavily_extract`	Pull clean content from one or more URLs.
`tavily_crawl`	Read many pages across a site.
`tavily_map`	Discover a site’s structure.
`tavily_research`	Run multi-source research and return a detailed answer.

Client setup details

Connect to Claude Code

Claude Code natively supports remote MCP servers with OAuth authentication. Add Tavily to your Claude Code configuration by running:

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

When you start a new conversation, Claude Code will open a browser window for you to complete the OAuth flow and authorize access to your Tavily account. No API key needed in the URL — authentication is handled automatically via OAuth. You can also manually add the following to your .claude/settings.json:

{
  "mcpServers": {
    "tavily": {
      "type": "http",
      "url": "https://mcp.tavily.com/mcp/"
    }
  }
}

Alternatively, you can also connect using mcp-remote:

claude mcp add tavily -- npx -y mcp-remote https://mcp.tavily.com/mcp

Connect to Claude Desktop

Click Add to Claude at the top of this page, or open the Tavily connector in Claude’s directory, click Connect, and sign in to Tavily. See the Claude guide for organization-wide access and the Tavily plugin.

Connect to Cursor

For the recommended Tavily plugin, standalone setup options, and examples, see the Cursor guide. The Add to Cursor button above installs the server with OAuth. To use an API key instead, add this to your mcp.json and replace <your-api-key> with your Tavily API key:

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

OpenAI Responses API

Allow OpenAI models to use the remote Tavily MCP server to perform tasks.

Export your OPENAI_API_KEY.
Replace <your-api-key> with your Tavily API key.

import json

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "tavily",
            "server_url": "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>",
            "require_approval": "never",
            ## Optional default parameters:
            "headers": {
                "DEFAULT_PARAMETERS": json.dumps({
                    "include_favicon": True,
                    "include_images": False,
                    "include_raw_content": False,
                }),
            },
        },
    ],
    input="Do you have access to the tavily mcp server?",
)

print(resp.output_text)

Clients that don’t support remote MCPs

mcp-remote is a lightweight bridge that lets MCP clients that can only talk to local (stdio) servers securely connect to remote MCP servers over HTTP + SSE with OAuth-based auth, so you can host and update your server in the cloud while existing clients keep working. It serves as an experimental stop-gap until popular MCP clients natively support remote, authorized servers.

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

OAuth Authentication

The Tavily Remote MCP server supports secure OAuth authentication, allowing you to connect and authorize seamlessly with compatible clients.

Using MCP Inspector

Open the MCP Inspector and click “Open Auth Settings”. Select the OAuth flow and complete these steps:

Metadata discovery
Client registration
Preparing authorization
Request authorization and obtain the authorization code
Token request
Authentication complete

Once finished, you will receive an access token that lets you securely make authenticated requests to the Tavily Remote MCP server.

Using Other MCP Clients

You can configure your MCP client to use OAuth without including your Tavily API key in the URL. For example, in Cursor’s mcp.json:

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

If you need to clear stored OAuth credentials and reauthenticate, run:

rm -rf ~/.mcp-auth

API Key Selection for OAuthWhen using OAuth authentication, you can control which API key is used by naming a key mcp_auth_default in your Tavily dashboard:

Personal account: If you have a key named mcp_auth_default in your personal account, it will be used for all OAuth-authenticated requests.
Team account: If your team has a key named mcp_auth_default, it will be used for all OAuth-authenticated requests.
Both set: If both your personal account and your team have a key named mcp_auth_default, the personal key takes priority.
Neither set: If no mcp_auth_default key exists, the default key in your personal account will be used. If no default key is set, the first available key will be used.

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.

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. Example:

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

Session & User Attribution

The remote MCP server automatically attaches identifiers to every Tavily API call so requests can be attributed back to a session. It generates X-Session-Id on its own, while X-Human-Id is forwarded only when supplied by the client.

X-Session-Id — generated per MCP session (the mcp-session-id returned during the MCP initialize handshake). All tool calls within the same MCP session share the same value.
X-Human-Id — if your client provides an X-Human-Id header (or humanId query parameter on the MCP URL), it is forwarded through to the Tavily API, helping Tavily better understand multi-step interactions and improve response quality. For security, Tavily hashes human IDs before processing or storing them.

See Session Tracking for the underlying API contract.

Local Installation

You can also run the Tavily MCP server on your own machine instead of using the remote server.

Prerequisites

Required Tools

Tavily API key
- If you don’t have a Tavily API key, you can sign up for a free account here
An MCP client, such as Claude Desktop or Cursor
Node.js (v20 or higher)
- You can verify your Node.js installation by running:
  node --version

Git Installation (Optional)

Only needed if using Git installation method:

On macOS: brew install git
On Linux:
- Debian/Ubuntu: sudo apt install git
- RedHat/CentOS: sudo yum install git
On Windows: Download Git for Windows

npx -y tavily-mcp@latest

git clone https://github.com/tavily-ai/tavily-mcp.git
cd tavily-mcp
npm install
npm run build

Although you can launch a server on its own, it’s not particularly helpful in isolation. Instead, you should integrate it into an MCP client.

Configuring MCP Clients

Cursor
Claude Desktop

Follow the local MCP setup in the Cursor guide to configure the server in mcp.json, add your Tavily API key, and enable its tools in Customize.

# Create the config file if it doesn't exist
touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

# Opens the config file in TextEdit
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

# Alternative method using Visual Studio Code
code "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

code %APPDATA%\Claude\claude_desktop_config.json

Add this configuration (replace tvly-YOUR_API_KEY-here with your Tavily API key):

Configuration

{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "tvly-YOUR_API_KEY-here"
      }
    }
  }
}

Default parameters for local servers

For local MCP setups, you can set default parameter values using the DEFAULT_PARAMETERS environment variable. This allows you to configure default search behavior without specifying these parameters in every request.

{
  "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\"}"
      }
    }
  }
}

Session attribution for local servers

The local MCP server automatically attaches identifiers to every Tavily API call so requests can be attributed back to a session:

X-Session-Id — auto-generated once per MCP process and reused for every tool call.
X-Human-Id — if you set the HUMAN_ID environment variable, that value is forwarded through to the Tavily API on every request, helping Tavily better understand multi-step interactions and improve response quality. For security, Tavily hashes human IDs before processing or storing them.

See Session Tracking for the underlying API contract.

Usage Examples

Tavily Search Examples

General Web Search:

Can you search for recent developments in quantum computing?

News Search:

Search for news articles about AI startups from the last 7 days.

Domain-Specific Search:

Search for climate change research on nature.com and sciencedirect.com

Tavily Extract Examples

Extract Article Content:

Extract the main content from this article: https://example.com/article

Combined Usage

Search for news articles about AI startups from the last 7 days and extract the main content from each article to generate a detailed report.

Troubleshooting

Server Not Found

If you encounter server connection issues, run these commands to verify your environment:

npm --version
node --version

Make sure to also check your configuration syntax for any errors.

NPX Issues

If experiencing problems with npx, locate your executable:

which npx

Once you have the path, update your configuration to use the full path to the npx executable.

API Key Issues

When troubleshooting API key problems, verify that your key is:

Properly formatted with the tvly- prefix
Valid and active in your Tavily dashboard
Correctly configured in your environment variables

You can test your API key validity by making a simple test request through the Tavily Playground

Resources

GitHub

tavily-ai/tavily-mcp

npm

tavily-mcp npm

Tutorial: Tavily MCP with Neo4j

Build a knowledge graph assistant by combining the Tavily and Neo4j MCP servers with Claude.

Model Context Protocol

Read the MCP specification.

Get started

Coding agents

API keys & credits

Best practices

Help

What you get

Client setup details

Connect to Claude Code

Connect to Claude Desktop

Connect to Cursor

OpenAI Responses API

Clients that don’t support remote MCPs

OAuth Authentication

Default Parameters

Session & User Attribution

Local Installation

Prerequisites

Configuring MCP Clients

Default parameters for local servers

Session attribution for local servers

Usage Examples

Troubleshooting

Resources

GitHub

npm

Tutorial: Tavily MCP with Neo4j

Model Context Protocol

​What you get

​Client setup details

​Connect to Claude Code

​Connect to Claude Desktop

​Connect to Cursor

​OpenAI Responses API

​Clients that don’t support remote MCPs

​OAuth Authentication

​Default Parameters

​Session & User Attribution

​Local Installation

​Prerequisites

​Configuring MCP Clients

​Default parameters for local servers

​Session attribution for local servers

​Usage Examples

​Troubleshooting

​Resources

GitHub

npm

Tutorial: Tavily MCP with Neo4j

Model Context Protocol

What you get

Client setup details

Connect to Claude Code

Connect to Claude Desktop

Connect to Cursor

OpenAI Responses API

Clients that don’t support remote MCPs

OAuth Authentication

Default Parameters

Session & User Attribution

Local Installation

Prerequisites

Configuring MCP Clients

Default parameters for local servers

Session attribution for local servers

Usage Examples

Troubleshooting

Resources