home / mcp / tavily mcp server

Tavily MCP Server

Provides four AI-friendly tools for real-time search, extraction, crawl, and map within the Klavis AI ecosystem.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jameskanyiri-tavily_mcp_server": {
      "command": "python",
      "args": [
        "src/server.py",
        "--port",
        "5002",
        "--log-level",
        "INFO",
        "--json-response"
      ],
      "env": {
        "TAVILY_API_KEY": "YOUR_TAVILY_API_KEY",
        "TAVILY_MCP_SERVER_PORT": "5002"
      }
    }
  }
}

You run the Tavily MCP Server to expose four atomic tools that integrate Tavily AI search capabilities into your workflows. This server handles real-time web search, extraction from pages, site crawling, and mapping a website’s structure, all with validation and clear error messages so you can build AI-assisted workflows confidently.

How to use

You connect an MCP client to this server to access four tools: tavily_search, tavily_extract, tavily_crawl, and tavily_map. Use these tools to perform live web searches, extract content from pages, explore a site’s structure, and map internal links. Each tool accepts a set of inputs and returns structured results that you can feed into follow-up prompts or pipelines.

How to install

Prerequisites you need before install: Python 3.12 or newer, a Tavily API key, and network access to reach Tavily services. The MCP server runs on port 5002 by default, but you can configure it.

# 1) Clone the Tavily MCP server repository
git clone https://github.com/jameskanyiri/tavily_mcp_server.git
cd tavily_mcp_server

# 2) Create and edit environment configuration
cp .env.example .env
# Edit .env and set TAVILY_API_KEY to your Tavily key

Next, create a Python virtual environment and install dependencies, then run the server. The server starts on port 5002 by default and can produce JSON responses for easier integration.

# 3) Create virtual env and install deps
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 4) Run the Tavily MCP server
python src/server.py --port 5002 --log-level INFO --json-response

Optionally, you can run the server with Docker. Build the image and run it on port 5002, passing your Tavily API key via an environment variable. The same port and environment variable usage apply.

# 5) Docker (optional)
docker build -t tavily_mcp_server -f Dockerfile .

docker run --rm -p 5002:5002 \
  -e TAVILY_API_KEY=tvly-YOUR_API_KEY \
  -e TAVILY_MCP_SERVER_PORT=5002 \
  tavily_mcp_server

Configuration and endpoints

The Tavily MCP server exposes an HTTP-based interface for real-time tool discovery and an optional streaming interface via SSE when connected through clients that support it. For client integrations, you typically point your MCP client to the server’s SSE endpoint at /sse and use the tool interfaces exposed by the server.

Environment variables you must configure for the server to operate are: TAVILY_API_KEY (required) and TAVILY_MCP_SERVER_PORT (defaults to 5002). These are necessary for authenticating with Tavily and for defining the server’s listening port.

{
  "mcpServers": {
    "tavily_mcp": {
      "type": "stdio",
      "name": "tavily_mcp",
      "command": "python",
      "args": ["src/server.py", "--port", "5002", "--log-level", "INFO", "--json-response"]
    }
  }
}

Important tools and inputs

The server provides four tools with validation and clear error messages. You pass inputs according to each tool’s purpose and the provided options.

{
  "tool": "tavily_search",
  "query": "latest AI developments",
  "search_depth": "basic",
  "max_results": 10,
  "include_raw_content": false
}

{
  "urls": ["https://example.com"],
  "extract_depth": "basic",
  "format": "markdown",
  "include_images": true
}

{
  "url": "https://www.example.org",
  "instructions": "Follow internal links only and extract page content as markdown.",
  "max_depth": 2,
  "format": "markdown"
}

{
  "url": "https://www.example.org/blog",
  "instructions": "Map the site structure focusing on primary navigation pages.",
  "max_depth": 3,
  "format": "markdown"
}

Security and maintenance notes

Keep your Tavily API key secure. Do not expose the key in client-side code or public repositories. Regularly rotate keys as recommended by Tavily and monitor usage for any unexpected activity.

If you change the listening port, ensure your MCP client configurations reflect the new URL and port. Use the TAVILY_MCP_SERVER_PORT environment variable to set the desired port.

Troubleshooting

Missing API key: ensure TAVILY_API_KEY is set. The server will raise a clear error at startup.

401/403: verify the API key is valid and has access to Tavily resources.

429: you are being rate-limited; back off and retry later.

Invalid input: validate your tool arguments against the supported schemas for each tool.

License

MIT license.

Available tools

tavily_search

Perform real-time web search with filters and optional raw content, images, and favicon, returning ranked results with title, URL, content snippet, and score.

tavily_extract

Extract cleaned text and optional images/favicon from specified URLs, returning per-URL content in a chosen format (markdown or text).

tavily_crawl

Crawl a site starting from a base URL with controls for depth, breadth, and optional extraction of content and images.

tavily_map

Generate a high-level map of a site’s structure, focusing on primary navigation, pages, and sections, with configurable depth and breadth.