My Tavily Search MCP Agent

I’ve created a powerful Model Context Protocol (MCP) Server powered by the Tavily API. With this, you can get high-quality, reliable information from business, news, finance, and politics - all through a robust and developer-friendly interface.

Why I Built Tavily Search MCP

In today’s fast-paced digital landscape, I recognized the need for quick access to precise information. I needed a web search tool that works with my sequential thinking MCP server. That’s why I developed Tavily Search MCP, which excels with:

Lightning-fast async search responses
Built-in fault tolerance with automatic retries
Clean, markdown-formatted results
Smart content snippets
Comprehensive error handling
Optional image results
Specialized news search

Quick Start

Installing via Smithery

To install Tavily Search for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install mcp-tavily-search --client claude

Installing Manually

Here’s how you can get up and running with my project in minutes:

# 1. Create environment
uv venv && .venvScriptsactivate     # Windows
# OR
uv venv && source .venv/bin/activate  # Unix/MacOS

# 2. Install dependencies
uv pip install -e .

# 3. Set up configuration
echo TAVILY_API_KEY=your-key-here > .env

# 4. Start server
cd mcp_tavily_search && uv run server.py

Core Features

Performance & Reliability

• I’ve implemented asynchronous request handling
• Built-in error handling and automatic retries
• Configurable request timeouts
• Comprehensive logging system

Search Configuration

• I’ve made the search depth configurable (basic/advanced)
• Adjustable result limits (1-20 results)
• Clean markdown-formatted output
• Snippet previews with source URLs
• Optional image results
• Specialized news search topic

Error Handling

• API authentication validation
• Rate limit detection
• Network error recovery
• Request timeout management

Developer Integration

Prerequisites

• Python 3.11 or higher
• UV Package Manager (Installation Guide)
• Tavily API key (Get one here)

Claude Desktop Setup

I’ve optimized the Claude Desktop experience with this configuration:

{
  "mcpServers": {
    "tavily-search": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-tavily-search/mcp_tavily_search",
        "run",
        "server.py"
      ],
      "env": {
        "TAVILY_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}

Configuration paths:

• Windows: %APPDATA%Claudeclaude_desktop_config.json
• Unix/MacOS: ~/.config/Claude/claude_desktop_config.json

Project Architecture

I’ve designed a clean, modular structure to make development a breeze:

mcp-tavily-search/
├── mcp_tavily_search/     # Core package
│   ├── server.py          # Server implementation
│   ├── client.py          # Tavily API client
│   ├── test_server.py     # Server tests
│   ├── test_client.py     # Client tests
│   └── __init__.py        # Package initialization
├── .env                   # Environment configuration
├── README.md              # Documentation
└── pyproject.toml         # Project configuration

Key Components

Server (server.py)

• I’ve implemented the MCP protocol
• Request handling and routing
• Error recovery and health monitoring

Client (client.py)

• Tavily API integration
• Retry mechanism with exponential backoff
• Result formatting and processing
• Error handling and logging

Tests (test_server.py and test_client.py)

• Comprehensive unit tests for both server and client
• Ensures reliability and correctness of the implementation

Usage Examples

Here are some examples of how to use the enhanced search capabilities I’ve implemented:

1. Basic search:

{
  "name": "search",
  "arguments": {
    "query": "Latest news on artificial intelligence"
  }
}

2. Advanced search with images:

{
  "name": "search",
  "arguments": {
    "query": "Elon Musk SpaceX achievements",
    "search_depth": "advanced",
    "include_images": true,
    "max_results": 10
  }
}

3. News-specific search:

{
  "name": "search",
  "arguments": {
    "query": "Climate change impact on agriculture",
    "topic": "news",
    "max_results": 5
  }
}

4. Search with raw content:

{
  "name": "search",
  "arguments": {
    "query": "Python programming best practices",
    "include_raw_content": true,
    "max_results": 3
  }
}

Troubleshooting Guide

Connection Issues

If things don’t work as expected, follow these steps I’ve outlined:

1. Verify your configuration paths
2. Check the Claude Desktop logs:

   # Windows
   type %APPDATA%Claudelogslatest.log
   # Unix/MacOS
   cat ~/.config/Claude/logs/latest.log
   

3. Test the server manually using the quick start commands

API Troubleshooting

If you’re experiencing API issues:

1. Validate your API key permissions
2. Check your network connection
3. Monitor the API response in the server logs

Running Tests

To run the unit tests for this project, follow these steps:

1. Install the development dependencies:

   uv pip install -e ".[dev]"
   

2. Run the tests using pytest:

   pytest mcp_tavily_search
   

This will run all the tests in the mcp_tavily_search directory, including both test_client.py and test_server.py.

Community and Support

• I encourage you to report issues and contribute on GitHub
• Share your implementations and improvements
• Join our discussions and help others

Security and Best Practices

Security is paramount in my implementation. The server includes:

• Secure API key handling through environment variables
• Automatic request timeout management
• Comprehensive error tracking and logging

License

I’ve licensed this project under MIT. See the LICENSE file for details.

Acknowledgments

I’d like to give special thanks to:

• The innovative Tavily API team
• The MCP protocol community