Tavily MCP Server

MIT License
49
  • Linux
  • Apple

Tavily MCP Server

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.

Features

Available Tools

  • tavily_web_search - Performs comprehensive web searches with AI-powered content extraction.
    • query (string, required): Search query
    • max_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 results
    • exclude_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 query
    • max_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 results
    • exclude_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 query
    • max_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 results
    • exclude_domains (list or string, optional): List of domains to exclude from results

Prompts

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

Prerequisites

  • Python 3.11 or later
  • A Tavily API key (obtain from Tavily's website)
  • uv Python package manager (recommended)

Installation

Option 1: Using pip or uv

# 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 [...]

Option 2: From source

# 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.

Usage with VS Code

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 pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

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

Note that the mcp key is not needed in the .vscode/mcp.json file.

{ "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}" } } } } }

Configuration

API Key Setup

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

  1. Through a .env file in your project directory:
    TAVILY_API_KEY=your_api_key_here
  2. As an environment variable:
    export TAVILY_API_KEY=your_api_key_here
  3. As a command-line argument:
    python -m mcp_server_tavily --api-key=your_api_key_here

Configure for Claude.app

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.

Usage Examples

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

Testing

The project includes a comprehensive test suite. To run the tests:

  1. Install test dependencies:
    source .venv/bin/activate # If using a virtual environment uv sync --dev # Or: pip install -r requirements-dev.txt
  2. Run the tests:
    ./tests/run_tests.sh

You should see output similar to:

======================================================= 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.

Docker

Build the Docker image:

make docker-build

Alternatively, build directly with Docker:

docker build -t mcp_tavily .

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

make docker-run

Or manually:

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

Stop and remove the container:

make docker-stop

Follow container logs:

make docker-logs

You can override defaults by setting environment variables:

  • DOCKER_IMAGE: image name (default mcp_tavily)
  • DOCKER_CONTAINER: container name (default mcp_tavily_container)
  • HOST_PORT: host port to bind (default 8000)
  • CONTAINER_PORT: container port (default 8000)

Debugging

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

Contributing

We welcome contributions to improve mcp-tavily! Here's how you can help:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests to ensure they pass
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

For examples of other MCP servers and implementation patterns, see: https://github.com/modelcontextprotocol/servers

License

mcp-tavily is licensed under the MIT License. See the LICENSE file for details.

-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Provides AI-powered web search capabilities using Tavily's search API, enabling LLMs to perform sophisticated web searches, get direct answers to questions, and search recent news articles.

  1. Features
    1. Available Tools
    2. Prompts
  2. Prerequisites
    1. Installation
      1. Option 1: Using pip or uv
      2. Option 2: From source
      3. Usage with VS Code
    2. Configuration
      1. API Key Setup
      2. Configure for Claude.app
    3. Usage Examples
      1. Testing
        1. Docker
          1. Debugging
            1. Contributing
              1. License

                Related MCP Servers

                • -
                  security
                  A
                  license
                  -
                  quality
                  Tavily AI search API
                  Last updated -
                  1
                  26
                  Python
                  MIT License
                  • Apple
                  • Linux
                • A
                  security
                  A
                  license
                  A
                  quality
                  Integrates Tavily's search API with LLMs to provide advanced web search capabilities, including intelligent result summaries, domain filtering for quality control, and configurable search parameters.
                  Last updated -
                  3
                  64
                  9
                  JavaScript
                  MIT License
                  • Linux
                • A
                  security
                  A
                  license
                  A
                  quality
                  An MCP server implementation that integrates the Tavily Search API, providing optimized search capabilities for LLMs.
                  Last updated -
                  1
                  TypeScript
                  MIT License
                  • Apple
                • A
                  security
                  A
                  license
                  A
                  quality
                  This server enables AI systems to integrate with Tavily's search and data extraction tools, providing real-time web information access and domain-specific searches.
                  Last updated -
                  2
                  5,133
                  334
                  JavaScript
                  MIT License
                  • Apple
                  • Linux

                View all related MCP servers

                ID: wr9q9l8lh1