Search Skill

Search the web and get relevant results optimized for LLM consumption.

Authentication

The script uses OAuth via the Tavily MCP server. No manual setup required - on first run, it will:

• Check for existing tokens in ~/.mcp-auth/

• If none found, automatically open your browser for OAuth authentication

Note: You must have an existing Tavily account. The OAuth flow only supports login — account creation is not available through this flow. Sign up at tavily.com first if you don't have an account.

Alternative: API Key

If you prefer using an API key, get one at https://tavily.com and add to ~/.claude/settings.json:

{

  "env": {

    "TAVILY_API_KEY": "tvly-your-api-key-here"

  }

}

Quick Start

Using the Script

./scripts/search.sh '<json>'

Examples:

# Basic search

./scripts/search.sh '{"query": "python async patterns"}'

# With options

./scripts/search.sh '{"query": "React hooks tutorial", "max_results": 10}'

# Advanced search with filters

./scripts/search.sh '{"query": "AI news", "time_range": "week", "max_results": 10}'

# Domain-filtered search

./scripts/search.sh '{"query": "machine learning", "include_domains": ["arxiv.org", "github.com"], "search_depth": "advanced"}'

Basic Search

curl --request POST \

  --url https://api.tavily.com/search \

  --header "Authorization: Bearer $TAVILY_API_KEY" \

  --header 'Content-Type: application/json' \

  --data '{

    "query": "latest developments in quantum computing",

    "max_results": 5

  }'

Advanced Search

curl --request POST \

  --url https://api.tavily.com/search \

  --header "Authorization: Bearer $TAVILY_API_KEY" \

  --header 'Content-Type: application/json' \

  --data '{

    "query": "machine learning best practices",

    "max_results": 10,

    "search_depth": "advanced",

    "include_domains": ["arxiv.org", "github.com"]

  }'

API Reference

Endpoint

POST https://api.tavily.com/search

Headers

Header

Value

Authorization

Bearer <TAVILY_API_KEY>

Content-Type

application/json

Request Body

Field

Type

Default

Description

query

string

Required

Search query (keep under 400 chars)

max_results

integer

10

Maximum results (0-20)

search_depth

string

"basic"

ultra-fast, fast, basic, advanced

topic

string

"general"

Search topic (general only)

time_range

string

null

day, week, month, year

start_date

string

null

Return results after this date (YYYY-MM-DD)

end_date

string

null

Return results before this date (YYYY-MM-DD)

include_domains

array

[]

Domains to include (max 300)

exclude_domains

array

[]

Domains to exclude (max 150)

country

string

null

Boost results from a specific country (general topic only)

include_raw_content

boolean

false

Include full page content

include_images

boolean

false

Include image results

include_image_descriptions

boolean

false

Include descriptions for images

include_favicon

boolean

false

Include favicon URL for each result

Response Format

{

  "query": "latest developments in quantum computing",

  "results": [

    {

      "title": "Page Title",

      "url": "https://example.com/page",

      "content": "Extracted text snippet...",

      "score": 0.85

    }

  ],

  "response_time": 1.2

}

Search Depth

Depth

Latency

Relevance

Content Type

ultra-fast

Lowest

Lower

NLP summary

fast

Low

Good

Chunks

basic

Medium

High

NLP summary

advanced

Higher

Highest

Chunks

When to use each:

• ultra-fast: Real-time chat, autocomplete

• fast: Need chunks but latency matters

• basic: General-purpose, balanced

• advanced: Precision matters (default recommendation)

Examples

Domain-Filtered Search

curl --request POST \

  --url https://api.tavily.com/search \

  --header "Authorization: Bearer $TAVILY_API_KEY" \

  --header 'Content-Type: application/json' \

  --data '{

    "query": "Python async best practices",

    "include_domains": ["docs.python.org", "realpython.com", "github.com"],

    "search_depth": "advanced"

  }'

Search with Full Content

curl --request POST \

  --url https://api.tavily.com/search \

  --header "Authorization: Bearer $TAVILY_API_KEY" \

  --header 'Content-Type: application/json' \

  --data '{

    "query": "React hooks tutorial",

    "max_results": 3,

    "include_raw_content": true

  }'

Tips

• Keep queries under 400 characters - Think search query, not prompt

• Break complex queries into sub-queries - Better results than one massive query

• **Use include_domains** to focus on trusted sources

• **Use time_range** for recent information

• **Filter by score** (0-1) to get highest relevance results