Tavily MCP Server Cursor IDE Setup 2026

How do you set up the Tavily MCP server in Cursor? Add a tavily-mcp entry under mcpServers in ~/.cursor/mcp.json that runs npx -y tavily-mcp@latest with a TAVILY_API_KEY environment variable, or connect to Tavily's hosted remote endpoint at https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key> via mcp-remote. Get the key from your account at app.tavily.com. Restart Cursor, confirm a green status, then ask it to search the live web for something — a real, current result back confirms the key and connection are working.

This page covers tavily-ai/tavily-mcp, Tavily's own maintained MCP server, purpose-built to give an agent real-time web search, page extraction, site mapping, and crawling — not a general web-scraping toolkit, but four specific tools aimed at the "let the model look something up itself" use case that comes up constantly once you're building agents in Cursor rather than just chatting with one.

Why an agent needs this instead of just asking the model

A language model's training data has a cutoff. Tavily's MCP server exists to close that gap during an agent session: instead of guessing at a fact, price, or current API detail, the agent calls tavily-search, gets back live results, and reasons over those instead of its own stale knowledge. That's a meaningfully different job than the "search the codebase" or "search Notion" tools covered elsewhere on this site — this one reaches outside anything you own.

Quick reference

Prerequisites

Step 1: Get a Tavily API key

1. Go to app.tavily.com and create an account, or log in if you already have one.
2. Your API key is available from the account dashboard once you're logged in. Free-tier keys are prefixed tvly- and work immediately with either setup path below.
3. Treat it like any other API credential — don't commit it into a shared mcp.json, and prefer an environment variable over a hardcoded string when the config file might end up in version control.

Step 2: Local setup — npx (recommended to start)

This is the simplest path and matches Tavily's own README example, adapted for Cursor's mcpServers schema:

{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "tvly-YOUR_API_KEY_HERE"
      }
    }
  }
}

Save to ~/.cursor/mcp.json for a connection available in every project, or .cursor/mcp.json for one repo only. Restart Cursor and check Settings → Tools & Integrations → MCP Tools for a green dot next to tavily-mcp. The first run downloads the package via npx; expect a short delay the very first time the server starts.

Tavily's README also documents an optional DEFAULT_PARAMETERS env var — a JSON string that sets defaults applied to every search unless a call overrides them:

{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "tvly-YOUR_API_KEY_HERE",
        "DEFAULT_PARAMETERS": "{\"include_images\": true, \"max_results\": 15, \"search_depth\": \"advanced\"}"
      }
    }
  }
}

This is useful if you consistently want deeper search results by default rather than repeating the same parameters in every prompt.

Step 3: Remote setup — hosted endpoint via mcp-remote

Tavily also hosts the server directly, so you don't need Node's npx cycle running locally at all. The remote URL takes the API key as a query parameter:

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

Tavily's docs also support passing the key as an Authorization: Bearer header instead of a URL parameter, for clients that prefer not to put credentials in a URL, and support OAuth for compatible clients — configurable via a mcp_auth_default key setting in the Tavily dashboard that controls which underlying API key OAuth-authenticated requests use. The URL-parameter form above is the simplest for most MCP clients and the one Tavily documents first.

Step 4: Verify the connection

Search the web for the current status of the Node.js LTS release schedule and summarize what you find.

A response with specific, current information — not a hedge about training-data cutoffs — confirms the key and connection are both working. If Cursor answers from memory instead of calling the tool, check that the server shows green in MCP Tools before assuming the query itself was the problem.

Available tools

Tavily's server exposes four tools, not just search:

Search and extract cover most day-to-day "find this fact" agent workflows in Cursor. Map and crawl matter more for a heavier research or site-analysis task where the agent needs to understand a whole site's structure, not just answer one question.

Session tracking

The remote server automatically generates an X-Session-Id per session and will forward an X-Human-Id header if your client supplies one. Tavily's stated purpose for this is understanding multi-step interactions across a session rather than treating every call as unrelated — worth knowing if you're debugging inconsistent results across what feels like one continuous research task.

Practical workflows

Fact-checking a claim before it goes into a document:

Search the web to confirm whether the statistic I just wrote about npm's weekly download count is still accurate, and cite the source.

Pulling a changelog you don't have memorized:

Extract the content from https://example.com/changelog and summarize what changed in the last three releases.

Scoping a competitor's site before writing about it:

Map example-competitor.com and tell me what sections of the site exist before we decide what to crawl for the comparison page.

Troubleshooting

Server never appears in Cursor. Confirm the file is .cursor/mcp.json or ~/.cursor/mcp.json, the top-level key is mcpServers, and the JSON is valid — one syntax error drops every server defined in that file, not just this one.

First run hangs or times out. The local path downloads the tavily-mcp package via npx on first launch. A slow or blocked network connection to the npm registry will look like a hang. Try running npx -y tavily-mcp@latest directly in a terminal to see the actual download progress and any error text Cursor's UI might be hiding.

401 or invalid-key errors. Confirm the key was copied in full — Tavily keys start with tvly- — and that it's set as TAVILY_API_KEY in the env block for the local path, or correctly URL-encoded as the tavilyApiKey query parameter for the remote path. A key with special characters copied incorrectly into a URL is a common, easy-to-miss cause.

Remote path fails to connect but local works fine. The remote setup depends on mcp-remote running correctly as a proxy — confirm npx can reach the npm registry for that package too, separately from tavily-mcp itself. If your network blocks outbound requests to mcp.tavily.com, the local npx tavily-mcp path avoids that dependency entirely since it calls Tavily's API directly rather than through the remote MCP endpoint's own proxy layer.

Results look shallow or too broad. Adjust DEFAULT_PARAMETERS — bumping search_depth to "advanced" and raising max_results both push toward more thorough results at the cost of a slower, heavier call. There's no per-prompt way to override defaults without either editing the config or explicitly asking the agent to request different parameters, so keep the default tuned to what most of your queries actually need.

Agent never calls the tool, just answers from memory. Confirm Tavily shows green in Cursor's MCP Tools panel before assuming the prompt is at fault — a model with tools available doesn't always reach for them unless the question makes it obvious a live lookup would help. Being explicit ("search the web for...") in the prompt makes tool selection more reliable than a vague, answerable-from-training-data question.

When not to use this

Don't wire an unrestricted tavily-crawl call into a fully autonomous loop against a large, unfamiliar site without limits — crawling is billed against your Tavily usage the same way search and extract calls are, and a broad, un-scoped crawl instruction can burn through a plan's request budget faster than a handful of targeted searches would. Scope the map or crawl request to a specific subsection when you can, rather than pointing it at an entire domain by default.

Frequently Asked Questions

What's the short version of Tavily MCP Cursor setup? Add a tavily-mcp entry under mcpServers in mcp.json running npx -y tavily-mcp@latest with TAVILY_API_KEY set in the env block, or use the remote URL https://mcp.tavily.com/mcp/?tavilyApiKey=<key> via mcp-remote. Restart Cursor and confirm the green dot before testing a live search.

Do I need Node.js installed? For the local npx path, yes — npx ships with Node.js. The remote path also runs through npx -y mcp-remote, so Node is effectively required either way in current setups.

What tools does the Tavily MCP server expose? Four: tavily-search for real-time web search, tavily-extract for pulling content from a known URL, tavily-map for structuring a site's page layout, and tavily-crawl for systematically walking a website.

Can I set default search parameters instead of repeating them in every prompt? Yes, via the DEFAULT_PARAMETERS environment variable — a JSON string (for example {"include_images": true, "max_results": 15, "search_depth": "advanced"}) applied to every search unless a specific call overrides it.

Local npx or remote — which should I use? Local npx is simpler to start with and doesn't depend on Tavily's remote proxy layer being reachable from your network. The remote path via mcp-remote avoids running Node processes locally on every launch and supports OAuth for clients that prefer it over a raw API key.

Is there a free tier to test with? Yes — signing up at app.tavily.com provides a free-tier API key sufficient to get the setup working and test all four tools before deciding on a paid plan for heavier use.

Related guides

Official docs cited