A Model Context Protocol server that provides AI-powered web search capabilities using Tavily's search API. This server enables LLMs to perform sophisticated web searches, get direct answers to questions, and search recent news articles with AI-extracted relevant content.
-
tavily_web_search
- Performs comprehensive web searches with AI-powered content extraction.query
(string, required): Search querymax_results
(integer, optional): Maximum number of results to return (default: 5, max: 20)search_depth
(string, optional): Either "basic" or "advanced" search depth (default: "basic")include_domains
(list or string, optional): List of domains to specifically include in resultsexclude_domains
(list or string, optional): List of domains to exclude from results
-
tavily_answer_search
- Performs web searches and generates direct answers with supporting evidence.query
(string, required): Search querymax_results
(integer, optional): Maximum number of results to return (default: 5, max: 20)search_depth
(string, optional): Either "basic" or "advanced" search depth (default: "advanced")include_domains
(list or string, optional): List of domains to specifically include in resultsexclude_domains
(list or string, optional): List of domains to exclude from results
-
tavily_news_search
- Searches recent news articles with publication dates.query
(string, required): Search querymax_results
(integer, optional): Maximum number of results to return (default: 5, max: 20)days
(integer, optional): Number of days back to search (default: 3)include_domains
(list or string, optional): List of domains to specifically include in resultsexclude_domains
(list or string, optional): List of domains to exclude from results
The server also provides prompt templates for each search type:
- tavily_web_search - Search the web using Tavily's AI-powered search engine
- tavily_answer_search - Search the web and get an AI-generated answer with supporting evidence
- tavily_news_search - Search recent news articles with Tavily's news search
- Python 3.13 or later
- A Tavily API key (obtain from Tavily's website)
uv
Python package manager (recommended)
# With pip
pip install mcp-tavily
# Or with uv (recommended)
uv add mcp-tavily
You should see output similar to:
Resolved packages: mcp-tavily, mcp, pydantic, python-dotenv, tavily-python [...]
Successfully installed mcp-tavily-0.1.4 mcp-1.0.0 [...]
# Clone the repository
git clone https://github.com/RamXX/mcp-tavily.git
cd mcp-tavily
# Create a virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies and build
uv sync # Or: pip install -r requirements.txt
uv build # Or: pip install -e .
# To install with test dependencies:
uv sync --dev # Or: pip install -r requirements-dev.txt
During installation, you should see the package being built and installed with its dependencies.
The server requires a Tavily API key, which can be provided in three ways:
-
Through a
.env
file in your project directory:TAVILY_API_KEY=your_api_key_here
-
As an environment variable:
export TAVILY_API_KEY=your_api_key_here
-
As a command-line argument:
python -m mcp_server_tavily --api-key=your_api_key_here
Add to your Claude settings:
"mcpServers": {
"tavily": {
"command": "python",
"args": ["-m", "mcp_server_tavily"]
},
"env": {
"TAVILY_API_KEY": "your_api_key_here"
}
}
If you encounter issues, you may need to specify the full path to your Python interpreter. Run which python
to find the exact path.
For a regular web search:
Tell me about Anthropic's newly released MCP protocol
To generate a report with domain filtering:
Tell me about redwood trees. Please use MLA format in markdown syntax and include the URLs in the citations. Exclude Wikipedia sources.
To use answer search mode for direct answers:
I want a concrete answer backed by current web sources: What is the average lifespan of redwood trees?
For news search:
Give me the top 10 AI-related news in the last 5 days
The project includes a comprehensive test suite. To run the tests:
-
Install test dependencies:
source .venv/bin/activate # If using a virtual environment uv sync --dev # Or: pip install -r requirements-dev.txt
-
Run the tests:
./tests/run_tests.sh
You should see output similar to:
============================= test session starts ==============================
collected 27 items
tests/test_models.py ................. [ 62%]
tests/test_utils.py ..... [ 81%]
tests/test_integration.py ..... [100%]
---------- coverage: platform darwin, python 3.13.2-final-0 ----------
Name Stmts Miss Cover
-------------------------------------------------------
src/mcp_server_tavily/__init__.py 16 2 88%
src/mcp_server_tavily/__main__.py 2 2 0%
src/mcp_server_tavily/server.py 137 80 42%
-------------------------------------------------------
TOTAL 155 84 46%
============================== 27 passed in 0.40s ==============================
The test suite includes tests for data models, utility functions, integration testing, error handling, and parameter validation. It focuses on verifying that all API capabilities work correctly, including handling of domain filters and various input formats.
You can use the MCP inspector to debug the server:
# Using npx
npx @modelcontextprotocol/inspector python -m mcp_server_tavily
# For development
cd path/to/mcp-tavily
npx @modelcontextprotocol/inspector python -m mcp_server_tavily
We welcome contributions to improve mcp-tavily! Here's how you can help:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Make your changes
- Run tests to ensure they pass
- Commit your changes (
git commit -m 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
For examples of other MCP servers and implementation patterns, see: https://github.com/modelcontextprotocol/servers
mcp-tavily is licensed under the MIT License. See the LICENSE file for details.