tavily-ai/tavily-mcp

What is Tavily MCP Server?

Tavily MCP is a lightweight, self‑hosted (or remotely‑hosted) MCP (Model Context Protocol) server that gives AI agents access to four web‑knowledge tools:

Tool	What it does	Typical AI use‑case
tavily‑search	Real‑time web search (Google‑like)	Retrieve up‑to‑date facts, news, or references while the model is generating a response
tavily‑extract	Pulls the main text, images, and metadata from a URL	Summarise a page, answer questions about its content, or feed the text into a downstream model
tavily‑map	Crawls a site and returns a structured site‑map (pages, hierarchy, links)	Build a knowledge graph of a documentation site or create a navigation aid for a chatbot
tavily‑crawl	Systematically explores a domain, returning a list of discovered URLs and their content	Gather a corpus for fine‑tuning, RAG indexing, or bulk analysis

The server follows the Model Context Protocol – a standard that lets LLM‑based tools (Claude Code, Cursor, etc.) call external services as if they were built‑in functions. By adding the Tavily MCP server to a client, the model can invoke any of the four tools with a simple JSON request.

How you run it

Remote (hosted by Tavily)

No installation needed – just point your client to https://mcp.tavily.com/mcp/ and supply a Tavily API key either in the URL (?tavilyApiKey=…) or via an Authorization: Bearer … header.
You can also send a DEFAULT_PARAMETERS header containing a JSON object to set default search options (e.g. {"include_images":true,"max_results":10}) for every request.

Local (run yourself)

Install Node 20+.
Run the package directly with NPX:
```
npx -y tavily-mcp@latest
```
Provide your API key and any optional env vars (see below) in the MCP client configuration.

Configuration knobs you might care about

Env var / header	Purpose	Example
`TAVILY_API_KEY`	Authenticates every tool call.	`TAVILY_API_KEY=sk_…`
`DEFAULT_PARAMETERS`	JSON of default search parameters (include images, depth, result count, etc.).	`{"include_images":true,"search_depth":"advanced","max_results":15}`
`TAVILY_HUMAN_ID`	Optional opaque identifier for the end‑user; sent as `X‑Human‑Id` (hashed server‑side).	`TAVILY_HUMAN_ID=12345`
OAuth flow	Instead of an API key in the URL you can run an OAuth dance (supported by the MCP Inspector, Cursor, etc.). The server will issue an access token that the client uses automatically.

How to hook it up to popular AI‑coding assistants

Claude Code (Anthropic)

# API‑key in URL
claude mcp add --transport http tavily https://mcp.tavily.com/mcp/?tavilyApiKey=<your-key>

# Or use the OAuth flow (no key in URL)
claude mcp add --transport http tavily https://mcp.tavily.com/mcp

After adding, run claude, type /mcp and follow the prompts to finish authentication. Adding --scope user makes the server available to all of your Claude projects.

Cursor (AI‑first IDE)

Click the “Add to Cursor” button in the README, then edit the generated mcp.json to insert your API key:

{
  "mcpServers": {
    "tavily-remote-mcp": {
      "command": "npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=<your-key>",
      "env": {}
    }
  }
}

You can also use the OAuth variant by omitting the key from the URL.

Who might use this?

Audience	Why it matters
LLM developers building agents that need up‑to‑date web info – they can call `tavily-search` directly from the model without writing custom scraping code.
RAG engineers who want a quick way to pull fresh documents from a site and feed them into a vector store – `tavily-crawl`/`tavily-map` give you a ready‑made corpus.
Productivity tool makers (e.g., VS Code extensions, AI notebooks) that want to add “search the web” or “summarise a page” as a built‑in command.
Researchers exploring how LLMs interact with live data – the remote server lets you experiment without managing infrastructure.

Quick “hello‑world” request (JSON format used by MCP clients)

{
  "tool": "tavily-search",
  "arguments": {
    "query": "latest GPT‑4 release notes",
    "max_results": 3,
    "include_images": false
  }
}

The server returns a list of result objects containing title, url, snippet, and (if requested) image_url.

Where to learn more

Tutorial – Building a Knowledge‑Graph Assistant (combines Tavily MCP with Neo4j).
Tutorial – Connect your coding assistant to the web (integrates Tavily MCP with the Cline VS Code extension).
The Model Context Protocol spec (the underlying API contract).
Anthropic’s Claude Code docs for adding custom MCP servers.

TL;DR

Tavily MCP is a ready‑to‑use server that turns web search, extraction, mapping, and crawling into standard MCP tools. You can run it locally with a single npx command or connect to Tavily’s hosted endpoint, then let any MCP‑compatible LLM client (Claude Code, Cursor, etc.) call those tools as if they were native functions. This gives AI agents reliable, real‑time access to the open web without writing their own scrapers.