Tavily Search

########################################################

I built this MCP server back in early March of 2025 when the MCP protocol was brand new and there were no consistent ways to do search in chatbots, predating other implementations.

Since then, the good folks at Tavily have released their officialTavily MCP serverwhich is well-maintained and in sync with their latest capabilities. Therefore, I'm now deprecating this server in favor of theirs.

- Python 3.11 or later
- A Tavily API key (obtain fromTavily's website)
- uvPython package manager (recommended)

# With pip pip install mcp-tavily # Or with uv (recommended) uv add mcp-tavily

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.

For quick installation, use one of the one-click install buttons below:

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressingCtrl + Shift + Pand typingPreferences: Open User Settings (JSON).

Optionally, you can add it to a file called.vscode/mcp.jsonin your workspace. This will allow you to share the configuration with others.

Note that themcpkey is not needed in the.vscode/mcp.jsonfile.

{ "mcp": { "inputs": [ { "type": "promptString", "id": "apiKey", "description": "Tavily API Key", "password": true } ], "servers": { "tavily": { "command": "uvx", "args": ["mcp-tavily"], "env": { "TAVILY_API_KEY": "${input:apiKey}" } } } } }

The server requires a Tavily API key, which can be provided in three ways:
-

Through a.envfile in your project directory:

python -m mcp_server_tavily --api-key=your_api_key_here

"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. Runwhich pythonto find the exact path.

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?

Give me the top 10 AI-related news in the last 5 days

The project includes a comprehensive test suite with automated dependency compatibility testing.

source .venv/bin/activate # If using a virtual environment uv sync --dev # Or: pip install -r requirements-dev.txt

./tests/run_tests.sh # Or using Make make test

To ensure the project works with the latest dependency versions, use these commands:

# Test with latest dependencies using Make make test-deps # Full compatibility test with verbose output make test-compatibility # Or use the standalone script ./scripts/test-compatibility.sh

- Update all dependencies to their latest versions
- Run the full test suite with coverage
- Report any compatibility issues
- Show version changes for transparency

The project includes automated dependency compatibility testing through GitHub Actions:

- Weekly Testing: Runs every Monday at 8 AM UTC
- Multi-Python Support: Tests against Python 3.11, 3.12, and 3.13
- Issue Creation: Automatically creates GitHub issues when tests fail
- Manual Trigger: Can be triggered manually from the GitHub Actions tab

When tests pass: Your project is compatible with the latest dependency versions. You can safely update your requirements files.

When tests fail: Review the test output to identify breaking changes, update your code to handle API changes, update tests if needed, or consider pinning problematic dependency versions.

======================================================= test session starts ======================================================== platform darwin -- Python 3.13.3, pytest-8.3.5, pluggy-1.5.0 rootdir: /Users/ramirosalas/workspace/mcp-tavily configfile: pyproject.toml plugins: cov-6.0.0, asyncio-0.25.3, anyio-4.8.0, mock-3.14.0 asyncio: mode=Mode.STRICT, asyncio_default_fixture_loop_scope=function collected 50 items tests/test_docker.py .. [ 4%] tests/test_integration.py ..... [ 14%] tests/test_models.py ................. [ 48%] tests/test_server_api.py ..................... [ 90%] tests/test_utils.py ..... [100%] ---------- coverage: platform darwin, python 3.13.3-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 149 16 89% ------------------------------------------------------- TOTAL 167 20 88%

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.

The project includes tools for building and releasing with the latest dependency versions:

# Build package with latest dependency versions make build-latest # Complete release workflow: test, build, and check with latest deps make release-all # Prepare a release with version management ./scripts/prepare-release.sh [new_version]

Recommended approach for releases with latest dependencies:
- Complete release preparation:make release-all
- Upload without downgrades:make upload-latest
- Test with latest dependencies:make test-compatibility
- Build for release:make release-build
- Upload without rebuilding:make upload-latest

Important: Usemake upload-latestinstead ofmake uploadto prevent dependency downgrades during the upload process. Theupload-latestcommand uses existing distribution files without reinstalling dependencies.

The release commands ensure your package is built and tested with the most recent compatible dependency versions, preventing the downgrades that can occur with traditional build chains.

Alternatively, build directly with Docker:

Run a detached Docker container (default namemcp_tavily_container, port 8000 → 8000):

docker run -d --name mcp_tavily_container \ -e TAVILY_API_KEY=your_api_key_here \ -p 8000:8000 mcp_tavily

You can override defaults by setting environment variables:

- DOCKER_IMAGE: image name (defaultmcp_tavily)
- DOCKER_CONTAINER: container name (defaultmcp_tavily_container)
- HOST_PORT: host port to bind (default8000)
- CONTAINER_PORT: container port (default8000)

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 theLICENSEfile for details.

Free search API for AI agents — 105 engines, 22 profiles, 94.3% SimpleQA accuracy, MCP server with 5 tools