mcp-tavily-search

A Model Context Protocol (MCP) server for integrating Tavily's search
API with LLMs. This server provides intelligent web search
capabilities optimized for high-quality, factual results, including
context generation for RAG applications and direct question answering.

Features

- 🔍 Advanced web search capabilities through Tavily API
- 🤖 AI-generated summaries of search results
- 🎯 Domain filtering for higher quality results
- 📊 Configurable search depth and parameters
- 🧠 Context generation for RAG applications
- ❓ Direct question answering capabilities
- 💾 Response caching with TTL support
- 📝 Multiple response formats (text, JSON, markdown)
- 🔄 Structured result formatting optimized for LLMs
- 🏗️ Built on the Model Context Protocol

Configuration

This server requires configuration through your MCP client. Here are
examples for different environments:

$3

Add this to your Cline MCP settings:

``json
{
"mcpServers": {
"mcp-tavily-search": {
"command": "npx",
"args": ["-y", "mcp-tavily-search"],
"env": {
"TAVILY_API_KEY": "your-tavily-api-key"
}
}
}
}
`

$3

For WSL environments, add this to your Claude Desktop configuration:

`json
{
"mcpServers": {
"mcp-tavily-search": {
"command": "wsl.exe",
"args": [
"bash",
"-c",
"source ~/.nvm/nvm.sh && TAVILY_API_KEY=your-tavily-api-key /home/username/.nvm/versions/node/v20.12.1/bin/npx mcp-tavily-search"
]
}
}
}
`

$3

The server requires the following environment variable:

- TAVILY_API_KEY: Your Tavily API key (required)

API

The server implements three MCP tools with configurable parameters:

$3

Search the web using Tavily Search API, optimized for high-quality,
factual results.

Parameters:

- query (string, required): Search query
- search_depth (string, optional): "basic" (faster) or "advanced"
(more thorough). Defaults to "basic"
- topic (string, optional): "general" or "news". Defaults to
"general"
- days (number, optional): Number of days back to search (news topic
only). Defaults to 3
- time_range (string, optional): Time range for results ('day',
'week', 'month', 'year' or 'd', 'w', 'm', 'y')
- max_results (number, optional): Maximum number of results.
Defaults to 5
- include_answer (boolean, optional): Include AI-generated summary.
Defaults to true
- include_images (boolean, optional): Include related images.
Defaults to false
- include_image_descriptions (boolean, optional): Include image
descriptions. Defaults to false
- include_raw_content (boolean, optional): Include raw HTML content.
Defaults to false
- include_domains (string[], optional): List of trusted domains to
include
- exclude_domains (string[], optional): List of domains to exclude
- response_format (string, optional): 'text', 'json', or 'markdown'.
Defaults to 'text'
- cache_ttl (number, optional): Cache time-to-live in seconds.
Defaults to 3600
- force_refresh (boolean, optional): Force fresh results ignoring
cache. Defaults to false

$3

Generate context for RAG applications using Tavily search.

Parameters:

- query (string, required): Search query for context generation
- max_tokens (number, optional): Maximum length of generated
context. Defaults to 2000
- search_depth (string, optional): "basic" or "advanced". Defaults
to "advanced"
- topic (string, optional): "general" or "news". Defaults to
"general"
- Other parameters same as tavily_search

$3

Get direct answers to questions using Tavily search.

Parameters:

- query (string, required): Question to be answered
- include_sources (boolean, optional): Include source citations.
Defaults to true
- search_depth (string, optional): "basic" or "advanced". Defaults
to "advanced"
- topic (string, optional): "general" or "news". Defaults to
"general"
- Other parameters same as tavily_search

Domain Filtering

The server supports flexible domain filtering through two optional
parameters:

- include_domains: Array of trusted domains to include in search
results
- exclude_domains: Array of domains to exclude from search results

This allows you to:

- Target specific trusted sources for academic or technical searches
- Exclude potentially unreliable or irrelevant sources
- Customize sources based on your specific needs
- Access all available sources when no filtering is specified

Example domain filtering:

`json
{
"include_domains": ["arxiv.org", "science.gov"],
"exclude_domains": ["example.com"]
}
`

Development

$3

1. Clone the repository
2. Install dependencies:

`bash
pnpm install
`

3. Build the project:

`bash
pnpm build
`

4. Run in development mode:

`bash
pnpm dev
`

$3

The project uses changesets for version management. To publish:

1. Create a changeset:

`bash
pnpm changeset
`

2. Version the package:

`bash
pnpm changeset version
`

3. Publish to npm:

`bash
pnpm release
``

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.

Acknowledgments

- Built on the
Model Context Protocol
- Powered by Tavily Search API