tavily-mcp

name	tavily-mcp
description	Search the web, extract page content, crawl sites, and conduct multi-source research via the Tavily MCP server. Use when user asks 'search for X', 'what's the latest on Y?', 'research this topic', 'extract content from this URL', 'crawl this website', 'map this site structure', or needs current web information, competitor analysis, or multi-source research. Do NOT use for library/framework documentation (use context7-mcp instead).
metadata	{"version":"1.0.0","mcp-server":"tavily","category":"web-research","tags":["search","web","research","extraction","crawling"]}

Tavily Web Search & Research

You are an expert at using the Tavily MCP server for web search, content extraction, site crawling, and multi-source research. Tavily provides high-quality, AI-optimized search results and deep content extraction.

Critical: These Are Direct Tool Calls

MCP tools are direct tool calls — exactly like Read, Grep, or Bash. They are NOT CLI commands.

CORRECT — call the tool directly:

Tool: mcp__tavily__tavily_search
Parameters: { "query": "Next.js 15 server actions best practices 2026" }

WRONG — do NOT shell out:

Bash: claude mcp call tavily tavily_search ...  # This does not work

All Tavily MCP tools use the mcp__tavily__ prefix.

Critical: Output Size Awareness

Tool	Output Size	Cost	Notes
tavily_search (basic)	Small-Medium	Low	5-10 results with snippets
tavily_search (advanced)	Medium	Medium	More results, deeper analysis
tavily_extract	Medium-Large	Medium	Full page content — scales with page size
tavily_crawl	Large-Very Large	High	Multiple pages — scales with depth/breadth settings
tavily_map	Medium	Low	URL list only (no content)
tavily_research	Very Large	Very High	Multi-source synthesis — use sparingly

Start with tavily_search for most questions. Only escalate to tavily_research for comprehensive multi-source analysis.

Workflow 1: Quick Search

Trigger: User asks a factual question, needs current information, or wants a quick answer.

Steps

1. Search with targeted query:

   tavily_search({
     query: "Supabase RLS best practices 2026",
     search_depth: "basic"
   })
   

2. If results are insufficient, try advanced search:

   tavily_search({
     query: "Supabase RLS best practices 2026",
     search_depth: "advanced"
   })
   

3. Optionally filter by domain:

   tavily_search({
     query: "Next.js middleware",
     include_domains: ["nextjs.org", "vercel.com"]
   })
   

Workflow 2: Extract Content from URL

Trigger: User provides a URL and wants its content, or search results point to a page needing deeper extraction.

Steps

1. Extract page content:

   tavily_extract({
     urls: ["https://example.com/article"],
     extract_depth: "basic"
   })
   

2. For protected sites or complex pages (tables, dynamic content):

   tavily_extract({
     urls: ["https://example.com/pricing"],
     extract_depth: "advanced"
   })
   

Note: tavily_extract can handle multiple URLs in parallel — pass them all in the urls array.

Workflow 3: Site Discovery & Crawling

Trigger: User says "explore this site", "what pages does this site have?", "crawl the docs", "map the site structure"

Steps

1. Map the site first (URL structure only, no content):

   tavily_map({
     url: "https://docs.example.com",
     max_depth: 2,
     max_urls: 50
   })
   

2. Then crawl specific sections (full content):

   tavily_crawl({
     url: "https://docs.example.com/guides",
     max_depth: 1,
     max_breadth: 10
   })
   

Key Patterns

• Always tavily_map before tavily_crawl — understand structure first, then extract content
• tavily_crawl defaults: max_depth: 1, max_breadth: 20 — increase carefully
• Crawling entire sites is expensive — target specific sections

Workflow 4: Deep Research

Trigger: User says "research this topic thoroughly", "give me a comprehensive analysis", "compare options for X"

Steps

1. Start with a search to gauge complexity:

   tavily_search({ query: "...", search_depth: "advanced" })
   

2. If a single search isn't enough, use research:

   tavily_research({
     query: "Comprehensive comparison of Supabase vs Firebase for multi-tenant SaaS in 2026",
     max_results: 10
   })
   

Use tavily_research sparingly — it makes multiple internal requests and produces very large output. Most questions are answered by tavily_search alone.

Decision Tree

User Needs	Best Tool	Why
Quick factual answer	tavily_search (basic)	Fast, low cost
Thorough search results	tavily_search (advanced)	More results, deeper snippets
Content from a specific URL	tavily_extract	Direct page content
Site structure overview	tavily_map	URL list only, no content
Multiple pages from a site	tavily_crawl	Follows links, extracts content
Comprehensive multi-source analysis	tavily_research	Multi-source synthesis (expensive)

Search Tips

• Include the year for current info: "React server components 2026" not just "React server components"
• Use include_domains to target authoritative sources: ["nextjs.org", "supabase.com"]
• Use exclude_domains to filter noise: ["medium.com", "w3schools.com"]
• Be specific: "Supabase RLS policies for multi-tenant SaaS with account_id" beats "Supabase security"

Troubleshooting

Search Returns Outdated Results

1. Add the current year to your query: "topic 2026"
2. Use search_depth: "advanced" for better results
3. Use include_domains to target official docs or recent sources

Extract Returns Empty or Partial Content

1. Try extract_depth: "advanced" for JavaScript-rendered pages
2. Some sites block extraction — fall back to WebFetch or browser_navigate (Playwright MCP)
3. Check if the URL requires authentication — Tavily cannot access authenticated content

Crawl Produces Too Much Output

1. Reduce max_depth (default 1 is usually sufficient)
2. Reduce max_breadth (default 20 — try 5-10 for targeted crawls)
3. Use tavily_map first to identify the specific URLs you need, then tavily_extract those URLs directly

Research Takes Too Long

tavily_research makes multiple internal API calls. If it's too slow:

1. Use tavily_search with search_depth: "advanced" instead
2. Run multiple targeted tavily_search calls in parallel
3. Only use tavily_research when comprehensive synthesis is truly needed