Tavily Search MCP Agent

# 🔍 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. [](https://smithery.ai/server/mcp-tavily-search) [](https://glama.ai/mcp/servers/p0w4whs3l4) [](https://github.com/your-username/mcp-tavily-search/actions) [](https://codecov.io/gh/your-username/mcp-tavily-search) ## 🌟 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](https://smithery.ai/server/mcp-tavily-search): ```bash 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: ```bash # 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](https://github.com/astral-sh/uv)) - Tavily API key ([Get one here](https://tavily.com)) ### Claude Desktop Setup I've optimized the Claude Desktop experience with this configuration: ```json { "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: 1. Basic search: ```json { "name": "search", "arguments": { "query": "Latest news on artificial intelligence" } } ``` 2. Advanced search with images: ```json { "name": "search", "arguments": { "query": "Elon Musk SpaceX achievements", "search_depth": "advanced", "include_images": true, "max_results": 10 } } ``` 3. News-specific search: ```json { "name": "search", "arguments": { "query": "Climate change impact on agriculture", "topic": "news", "max_results": 5 } } ``` 4. Search with raw content: ```json { "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: ```bash # Windows type %APPDATA%\Claude\logs\latest.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: ```bash uv pip install -e ".[dev]" ``` 2. Run the tests using pytest: ```bash 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