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

More agent context in BhavinM/my-claude-setup

19 other files this repository gives its agents.