Connect Tavily MCP Server to Claude Code: Full Guide

Adding search to Claude Code is the single highest-impact MCP server you can install. Most workflows — research, analysis, fact-checking, competitive intelligence — start with "find information about X." Without a search tool, your agent is limited to its training data. With one, it has the live web.

This guide walks through the complete tavily mcp server setup for claude code: from API key to working config to your first search query. Five minutes of setup, permanently better agent.

Prerequisites: API Key and Environment Setup

You need two things before touching the Claude Code config:

1. Tavily API key

Sign up at tavily.com and copy your API key from the dashboard. The free tier includes 1,000 searches per month — enough for daily use during development and light production.

Your key will look like: tvly-xxxxxxxxxxxxxxxxxxxxxxxx

2. Node.js and npx

The Tavily MCP server installs via npx, which comes with Node.js. Verify both are available:

node --version   # Should be v18+ 
npx --version    # Should return a version number

If npx isn't found, install or update Node.js from nodejs.org. This is the most common blocker — if things don't work later, check here first.

Step-by-Step Claude Code Configuration

Claude Code reads MCP server definitions from a JSON settings file. There are two locations:

• User-level: ~/.claude/settings.json — applies to all Claude Code sessions
• Project-level: .claude/settings.json in your project root — applies only to that project

Use user-level for Tavily since search is useful everywhere. Use project-level if you only want search in specific workspaces.

The complete tavily mcp json configuration

If the file doesn't exist yet, create it. If it does, add the tavily entry inside the existing mcpServers object:

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

That's the entire config. Let's break down what each field does:

• command: npx — runs the package without a global install
• args: ["-y", "tavily-mcp@latest"] — the -y auto-confirms the install prompt, @latest ensures you get the current version
• env: passes your API key to the server process as an environment variable

Alternative: environment variable reference

If you prefer not to hard-code the API key in the config file (recommended for shared or version-controlled configs):

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

Then set the key in your shell profile (.bashrc, .zshrc, etc.):

export TAVILY_API_KEY="tvly-your-actual-key-here"

Reload your shell or source the profile before starting Claude Code.

Testing Your Tavily Connection

Start a new Claude Code session (restart if one is already running — Claude Code reads MCP config at startup, not dynamically).

Ask something that requires current information:

What are the latest developments in the A2A protocol?

What you should see: A tool call to tavily_search in Claude Code's output, followed by results from the web, synthesized into an answer with source references.

If tools don't appear: Check these in order:

1. Config file location — Is the JSON in the right path? ~/.claude/settings.json for user-level.
2. JSON syntax — A missing comma or bracket breaks the entire file. Validate with cat ~/.claude/settings.json | python3 -m json.tool.
3. API key — Copy-paste it fresh from the Tavily dashboard. Keys start with tvly-.
4. npx availability — Run npx tavily-mcp@latest --help in your terminal. If this fails, the issue is Node/npx, not Claude Code.
5. Restart Claude Code — MCP servers connect at session start. Changes to config require a new session.

For a comprehensive troubleshooting walkthrough, see our MCP connection debugging guide.

Optimizing Search Modes for Different Tasks

Once connected, Tavily exposes three tools that Claude Code can call:

tavily_search

General web search. This is what the agent uses most often. Two depth modes:

• Basic — Fast, returns top results. Good for factual lookups, quick checks, and simple queries. Uses fewer API credits.
• Advanced — Deeper crawling, more sources, richer content. Better for research-grade queries where completeness matters. Uses more credits.

Claude Code picks the mode based on query complexity, but you can steer it:

Do a deep search on the current state of MCP security vulnerabilities.

vs.

Quick search: what's the current US inflation rate?

tavily_extract

Pulls full content from a specific URL. Use when you already know which page has the information:

Extract the full content from https://example.com/pricing

This is useful in chained workflows — search finds the right pages, extract pulls the complete content.

tavily_news_search

News-specific search filtered for recency and news sources. Better than general search when you need what happened this week, not background information.

Credit management

On the free tier (1,000 searches/month), each basic search costs 1 credit and advanced costs 2. At typical development usage (10-20 searches/day), the free tier lasts the full month. If you're running production workflows, monitor usage on the Tavily dashboard and upgrade as needed.

Full details on pricing and tiers at the Tavily listing on ClawsMarket.

Pairing Tavily with Other MCP Servers in Claude Code

Tavily handles discovery — finding relevant pages and information. But some workflows need more than search. Adding complementary MCP servers to the same Claude Code config creates powerful pipelines:

Tavily + NewsAPI

Tavily for broad research, NewsAPI for dedicated news coverage from 150,000+ sources. They cover different angles: Tavily gives you background context and general web results, NewsAPI gives you breaking news and media coverage. Together, they produce research that's both deep and current.

{
  "mcpServers": {
    "tavily": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": { "TAVILY_API_KEY": "${TAVILY_API_KEY}" }
    },
    "newsapi": {
      "command": "npx",
      "args": ["-y", "@newsapi/mcp-server"],
      "env": { "NEWSAPI_KEY": "${NEWSAPI_KEY}" }
    }
  }
}

Tavily + Apify

Search finds the right pages; Apify extracts structured data from them. When Tavily's search snippets don't contain enough detail — pricing tables, product specs, full feature matrices — hand the URLs to Apify for deep extraction.

Tavily + FRED API

Web research grounded in real economic data. Tavily finds qualitative analysis and news, FRED provides the hard numbers. The combination produces reports where every claim is backed by a source URL or a data series.

For a full walkthrough on combining multiple MCP servers, see our Claude Code automation guide.

Frequently Asked Questions

How do I add Tavily search to Claude Code?

Add a JSON configuration block to your Claude Code settings file (~/.claude/settings.json for all sessions or .claude/settings.json for a specific project). The block specifies the Tavily MCP server command (npx -y tavily-mcp@latest) and your API key as an environment variable. Restart Claude Code after saving the config — MCP servers connect at session start. Full JSON example is in the configuration section above.

Why isn't my Tavily MCP server connecting in Claude Code?

The most common causes: the settings JSON file has a syntax error (validate with a JSON linter), the API key is missing or incorrect (must start with tvly-), npx isn't installed or isn't in your PATH (test with npx --version), or Claude Code wasn't restarted after adding the config. Check each in order. Run npx tavily-mcp@latest --help in your terminal to verify the server package works independently of Claude Code.

Is Tavily free to use with Claude Code?

Tavily offers a free tier with 1,000 searches per month. Basic searches cost 1 credit each, advanced searches cost 2. At typical development usage (10-20 searches per day), the free tier lasts the month. The MCP server package itself is free and open-source — you only pay for Tavily API usage beyond the free tier. Paid plans are available for higher volumes.

Can I use Tavily with other MCP servers at the same time in Claude Code?

Yes. Add multiple server entries to the mcpServers object in your settings JSON. Claude Code discovers all connected servers at startup and makes their tools available simultaneously. The agent decides which tool to use based on the task. Common pairings: Tavily + NewsAPI (research + current events), Tavily + Apify (search + deep extraction), Tavily + FRED (research + economic data). Keep the total number of servers under eight to avoid tool selection confusion.

What's the difference between Tavily search modes?

Tavily exposes three tools: tavily_search (general web search with basic and advanced depth modes), tavily_extract (pull full content from a specific URL), and tavily_news_search (news-filtered search optimized for recency). Basic search is fast and credit-efficient for simple queries. Advanced search crawls deeper and returns richer results for research-grade questions. Extract is for when you already know which URL has the information. Claude Code selects the appropriate mode automatically, but you can steer it with explicit instructions like "do a deep search" or "quick search."