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
'
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
- 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