Verified MCP server: Tavily
The short answer
Last verified 2026-08-03
The Tavily MCP server gives an AI assistant a real search engine: it can search the live web, pull the readable text out of a page, crawl a site, map its URLs, and run a longer multi-source research pass. Tavily builds and ships it themselves, in two shapes that are both official. There is a hosted server at mcp.tavily.com that any client can dial over HTTPS, and there is an npm package you run on your own Mac. We ran both on the same afternoon with a key stored locally, enumerated all 5 tools, made one real search that came back with live results, and kept the raw output, including the exact errors it returns when the key is missing, wrong, or the arguments are incomplete. One naming trap is worth knowing before you start: the package is called tavily-mcp, with no scope. A badge on Tavily's own documentation page reads @tavily/mcp, and no package by that name exists on npm. [1][4][7][2]
Verification
Method
We spawned the npm package with npx over stdio, completed the MCP initialize handshake, called tools/list, and ran one real tool call that searched the live web. Authentication used a Tavily API key already stored on this Mac, read straight out of the local MCP configuration by the runner and never printed: every line the runner banks is passed through a redaction step first. The tool table below is the tools/list response, word for word. We then opened a second connection, this time to Tavily's hosted endpoint at https://mcp.tavily.com/mcp/ over Streamable HTTP with the same key, and it answered with the same five tools. Two more sessions were run on purpose to break things: one with no key at all, and one with a fake key. Both errors are printed further down.
Startup banner
Tavily MCP server running on stdio
One real tool call
tools/call tavily_search {"query": "what is MCP"}Detailed Results: Title: MCP 101: Understanding the Model Context Protocol URL: https://www.itential.com/resource/blog/mcp-101-understanding-the-model-context-protocol Content: ## What is MCP?
Real lines from the captured result: enough to prove the call answered.
Tools
The server answered tools/list with 5 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| tavily_searchquery*search_depthtopictime_rangestart_dateend_datemax_resultsinclude_imagesinclude_image_descriptionsinclude_raw_contentinclude_domainsexclude_domainscountryinclude_faviconexact_match | Search the web for current information on any topic. Use for news, facts, or data beyond your knowledge cutoff. Returns snippets and source URLs. |
| tavily_extracturls*extract_depthinclude_imagesformatinclude_faviconquery | Extract content from URLs. Returns raw page content in markdown or text format. |
| tavily_crawlurl*max_depthmax_breadthlimitinstructionsselect_pathsselect_domainsallow_externalextract_depthformatinclude_favicon | Crawl a website starting from a URL. Extracts content from pages with configurable depth and breadth. |
| tavily_mapurl*max_depthmax_breadthlimitinstructionsselect_pathsselect_domainsallow_external | Map a website's structure. Returns a list of URLs found starting from the base URL. |
| tavily_researchinput*model | Perform comprehensive research on a given topic or question. Use this tool when you need to gather information from multiple sources to answer a question or complete a task. Returns a detailed response based on the research findings. Rate limit: 20 requests per minute. |
Parameters marked with * are required.
Setup
Copy the block for the app you use. Each one is the configuration this server was verified with.
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"tavily-mcp": {
"command": "npx",
"args": [
"-y",
"tavily-mcp@latest"
],
"env": {
"TAVILY_API_KEY": "tvly-YOUR_API_KEY-here"
}
}
}
}Paste your own key, then quit and reopen Claude Desktop. This config file can only launch commands, so if you would rather use Tavily's hosted server here, bridge it: set the command to npx and the args to mcp-remote followed by https://mcp.tavily.com/mcp/?tavilyApiKey=your-key. [7][9]
One command in your terminal. This is the hosted server, so there is nothing to install:
claude mcp add tavily --transport http "https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-YOUR_API_KEY-here"
Add --scope user to make it available in every project instead of just this one. Two alternatives to putting the key in the URL: drop the query string entirely and run /mcp inside Claude Code to finish a browser OAuth flow, or skip the account altogether with --header "X-Tavily-Access-Mode: keyless", which gets you search and extract only. [7][8][10]
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"tavily-mcp": {
"command": "npx",
"args": [
"-y",
"tavily-mcp@latest"
],
"env": {
"TAVILY_API_KEY": "tvly-YOUR_API_KEY-here"
}
}
}
}Cursor picks the file up on restart. Treat that file the way you treat any file with a key in it: it is plain text on disk, so keep it out of a repository you push. [7][11]
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name Tavily Command npx Arguments -y tavily-mcp@latest Environment Variables TAVILY_API_KEY tvly-YOUR_API_KEY-here
The Arguments field splits on spaces, so keep it to exactly those three words. The key goes in Environment Variables, never in Arguments. Click Test Connection first: a working server answers with its tool count, five for this one. If you would rather use the hosted server, leave the form in URL (SSE/HTTP) mode and enter https://mcp.tavily.com/mcp/ with your key as the bearer token instead. [12][7]
No terminal needed
If you have never opened Terminal and never want to, this is your path. Routines is a Mac app that runs MCP servers for you: fill in a few fields once, and this server's tools are available to your AI in chat and in scheduled routines. The only detour is the Tavily key, and it takes about two minutes.
01
Download the app from getroutines.ai/download, drag it to Applications, and sign in.
02
Sign up at tavily.com, open the API Keys page in the dashboard, and copy the key that starts with tvly-. The free tier is enough to try everything on this page. If you only want search and extract and would rather not sign up at all, skip this step: the server runs without a key, and the troubleshooting section below explains exactly what changes.
03
Back in Routines, click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
04
The form opens in URL (SSE/HTTP) mode. Switch it to Command (stdio): the npm package is a command, not a web address. Name: Tavily. Command: npx. Arguments: -y tavily-mcp@latest, exactly those three words.
05
In Environment Variables add TAVILY_API_KEY with your tvly- key. Click Test Connection: Routines starts the server without saving it and reports how many tools it found, five for this one. Then click Add Server.
06
The tools work in chat right away. To let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
Every Monday at 8:00, search the web for news from the last seven days about my three main competitors, group what you find by company, and save it as competitor-watch.md in my Notes folder with a link under every line.
Every Tuesday at 9:00, extract the text of the pricing pages I listed in pricing-urls.md, compare each one with last week's copy saved in the same folder, and write only the changes to pricing-changes.md.
Every Friday at 15:00, research what changed this week in the topic I track, gather it from several sources, and write a one-page brief to research-brief.md with the three most useful links at the bottom.
Troubleshooting
Real errors captured during the verification run, printed exactly as the server returned them.
What you see
[tavily-mcp] no TAVILY_API_KEY set; running in keyless mode. Search and extract are available; other tools will return a message explaining that an API key is required.
The fix
This is the trap worth knowing about. With no key the server does not exit and does not complain: it boots into a free keyless tier where search and extract still answer, so everything looks healthy until a crawl fails. We triggered it on purpose by unsetting TAVILY_API_KEY. If your searches work but feel rate limited, read the startup output: this line is the only warning you get. In Routines the key goes in Environment Variables, in Claude Desktop and Cursor it goes in the env block.
What you see
This Tavily endpoint requires an API key. Keyless Tavily currently supports Search and Extract only. Retry using Search or Extract, or sign up at https://tavily.com for a Tavily API key. Continuation options: - Agentic payment (x402): - Sign up for a Tavily API key:
The fix
The same keyless mode, seen from the other end. This is what tavily_crawl returned for us when no key was set, and tavily_map and tavily_research behave the same way. It is a normal tool result, not a crash, so an assistant may report it as a polite refusal rather than a configuration problem. Add a real key and all five tools answer.
What you see
{"error":"Search failed","status":401,"detail":{"error":"Unauthorized: missing or invalid API key."},"documentation":"https://docs.tavily.com/documentation/api-reference/endpoint/search"}The fix
That is Tavily's answer, not the server's: your key reached them and they rejected it. We produced this by calling the hosted server with a made-up key. Check that you copied the whole key including the tvly- prefix, that you did not paste it with a trailing space, and that it has not been rotated in the dashboard. Note that connecting succeeds either way: the handshake is not authenticated, so a bad key only shows up on the first real call.
What you see
Tavily API error: [{"type":"missing","loc":["body","query"],"msg":"Field required","input":{"api_key":"tvly-REDACTED","raw_input":{"api_key":"tvly-REDACTED"}}}]
Documentation: https://docs.tavily.com/documentation/api-reference/endpoint/searchThe fix
A required argument never arrived. We caused this by calling tavily_search with no query at all, which is what happens when an assistant builds the call from an empty variable. Say what to search for in plain words and the argument fills itself. One thing to notice in that output: Tavily echoes your API key back inside the error payload. The two tvly-REDACTED values above are the only edit made to any captured text on this page, and they are there because that echo is real.
The fix
The npx command belongs to Node.js. If Node is not installed on your Mac, the Claude Desktop, Cursor and Routines configs above all fail at the spawn step before the server can say anything. Install Node from nodejs.org, restart your MCP client, and try again. The hosted server at mcp.tavily.com sidesteps this entirely: it needs no Node and no install.
FAQ
It is a small program that sits between an AI assistant and Tavily's search API and speaks the Model Context Protocol. Once connected, an assistant such as Claude can search the live web, read a page, crawl or map a site, and run a longer research pass, instead of guessing from whatever it learned before its cutoff. Tavily publishes it, and you can either run the npm package on your Mac over stdio or point your client at their hosted endpoint over HTTPS. [5][7]
The running server exposes 5 tools: tavily_search for live web search, tavily_extract for pulling readable content out of URLs, tavily_crawl for walking a site from a starting page, tavily_map for listing the URLs a site contains, and tavily_research for a multi-source research pass that Tavily rate limits to twenty requests a minute. The table above is the live tools/list output, word for word, and the hosted server answered with the same five.
For everything, yes: a Tavily key that starts with tvly-, from a free account at tavily.com. For search and extract only, no. We verified this by running the server with no key: it boots into a keyless mode, search and extract keep working against a free rate-limited tier, and crawl, map and research return a message telling you to sign up. That means a missing key does not look like a failure, which is the first entry in the troubleshooting section above. [8][6]
It reads the public web and sends nothing of yours except your query and your key, so the file-access risk that comes with local servers is not in play here. Two things do deserve care. Several of the documented setups put the key in a plain URL query string, which lands in shell history and in config files, so prefer the environment variable, the bearer header, or the OAuth flow. And search results are text written by strangers: treat anything the tool brings back as untrusted input, the same way you would treat a link in an email. [7]
No. In Routines you fill in the fields in Settings and click Test Connection; the walkthrough above shows every click, including the Tavily side. Claude Desktop needs a small JSON file edited once. Only Claude Code is terminal-first by nature. [12][9]
Any MCP client. Clients that launch a local command, such as Claude Desktop, Cursor and Routines, run the npm package over stdio. Clients that dial a web address, such as Claude Code and Routines in URL mode, connect to the hosted endpoint instead. A client that only speaks the local form can still reach the hosted server through the mcp-remote bridge, which is the shape shown in the Claude Desktop block above. [7][10][11][12]
Because they are two different builds of the same product, and we captured both on the same day. The npm package we spawned self-reported tavily-mcp 0.2.21, which matches the version on the registry. The hosted endpoint at mcp.tavily.com self-reported tavily-mcp 3.4.5 and advertised extra capabilities the local build did not, including prompts and resources. The tool list was identical across both, which is the part that matters when you are choosing between them. [1]
Sources
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
Latest version 0.2.21, published 2026-07-10, license MIT.
[2]
Returns not found. The scoped name shown as a badge label on Tavily's docs page is not a published package; the real one is unscoped.
[3]
[4]
2,288 stars, MIT license, not archived, last push 2026-07-30, per the GitHub API.
[5]
Remote and local install paths, client configs, and the optional DEFAULT_PARAMETERS and TAVILY_HUMAN_ID variables.
[6]
The keyless fallback when TAVILY_API_KEY is unset, and the five tool names.
[7]
The hosted endpoint, the local npm install, and the Claude Desktop, Claude Code and Cursor config shapes.
[8]
The keyless header mode, which covers search and extract only, and the rate limits that come with it.
[9]
The official Claude Desktop quickstart and the config file location.
[10]
The claude mcp add syntax, the --transport http flag, --scope user, and custom headers.
[11]
The mcp.json shape, including the env block, and the file locations.
[12]
How Routines runs one-click OAuth connectors and any MCP server.
This page describes Tavily as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. The briefs it writes stay markdown files on your Mac, and there is no cloud bill. Download Routines