🔍 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 && .venv\Scripts\activate     # 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%\Claude\claude_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:

Basic search:

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

Advanced search with images:

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

News-specific search:

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

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:

Verify your configuration paths
Check the Claude Desktop logs:
# Windows type %APPDATA%\Claude\logs\latest.log # Unix/MacOS cat ~/.config/Claude/logs/latest.log
Test the server manually using the quick start commands

API Troubleshooting

If you're experiencing API issues:

Validate your API key permissions
Check your network connection
Monitor the API response in the server logs

Running Tests

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

Install the development dependencies:
uv pip install -e ".[dev]"
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