📌Overview

Purpose: To provide AI-powered web search capabilities through a Model Context Protocol server utilizing Tavily's search API.

Overview: The Tavily MCP Server enhances the capability of language models to perform advanced web searches, retrieve direct answers, and access recent news content with relevant AI-extracted data. It serves as a bridge between AI models and comprehensive web search functionalities.

Key Features:

tavily_web_search: Enables comprehensive web searches, extracting AI-powered content to provide relevant information based on user queries.
tavily_answer_search: Performs searches and generates direct answers supported by evidence, effectively addressing user inquiries for precise information.
tavily_news_search: Facilitates the retrieval of recent news articles, allowing users to stay updated on current events by searching through a specified time frame.

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" (default: "basic")
- include_domains (list or string, optional): Domains to specifically include
- exclude_domains (list or string, optional): Domains to exclude
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 (default: 5, max: 20)
- search_depth (string, optional): Either "basic" or "advanced" (default: "advanced")
- include_domains (list or string, optional): Domains to specifically include
- exclude_domains (list or string, optional): Domains to exclude
tavily_news_search - Searches recent news articles with publication dates.
- query (string, required): Search query
- max_results (integer, optional): Maximum number of results (default: 5, max: 20)
- days (integer, optional): Number of days back to search (default: 3)
- include_domains (list or string, optional): Domains to specifically include
- exclude_domains (list or string, optional): Domains to exclude

Prompts

The server 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 https://tavily.com)
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

Option 2: From source

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

Usage with VS Code

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code (via Ctrl + Shift + P → Preferences: Open User Settings (JSON)), or to .vscode/mcp.json in your workspace:

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

Provide the Tavily API key by one of these methods:

.env file in your project directory:
```
TAVILY_API_KEY=your_api_key_here
```

Environment variable:

export TAVILY_API_KEY=your_api_key_here

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 needed, specify the full path to Python by running which python.

Usage Examples

Regular web search:

Tell me about Anthropic's newly released MCP protocol

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

Answer search mode for direct answers:

I want a concrete answer backed by current web sources: What is the average lifespan of redwood trees?

News search:

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

Testing

Run the test suite with:

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

The tests cover data models, utility functions, integration testing, error handling, and parameter validation.

Debugging

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 contribute:

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, visit:
https://github.com/modelcontextprotocol/servers

License

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