tavily-mcp

library0.2.3jsnpmunverified

The `tavily-mcp` package provides an advanced Model-Context-Protocol (MCP) server for real-time web search, data extraction, website mapping, and crawling, primarily designed for integration with AI agents like Anthropic's Claude. It ships as a server application (currently at version 0.2.18) rather than a traditional client-side JavaScript library, meaning developers typically interact with it via HTTP requests or dedicated client-side tooling (e.g., `claude mcp add`) rather than direct JavaScript function imports for basic usage. The server offers `tavily-search`, `tavily-extract`, `tavily-map`, and `tavily-crawl` tools. It can be run locally or accessed as a remote service, differentiating itself by providing structured web interaction capabilities for AI models.

llm-agents http-networking web-framework

npm install tavily-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TAVILY-MCP

tavily-mcp

llm-agentsjavascriptv0.2.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

McpServer

✓ import { McpServer } from 'tavily-mcp';

✗ const McpServer = require('tavily-mcp').McpServer;

Used for programmatic instantiation and management of the local MCP server in TypeScript/ESM projects.

TavilySearchTool

✓ import { TavilySearchTool } from 'tavily-mcp';

✗ import TavilySearchTool from 'tavily-mcp/search';

Imports the specific web search tool, often used when integrating individual tools into a custom MCP setup.

TavilyExtractTool

✓ import { TavilyExtractTool } from 'tavily-mcp';

✗ import { extract } from 'tavily-mcp';

Imports the data extraction tool for programmatic use, enabling intelligent parsing of web content.

Demonstrates how to programmatically start the Tavily MCP server locally and then make a basic search request to it, showcasing the server's core functionality.

import { McpServer, DEFAULT_MCP_SERVER_PORT } from 'tavily-mcp'; import axios from 'axios'; const TAVILY_API_KEY = process.env.TAVILY_API_KEY ?? ''; async function startAndTestServer() { if (!TAVILY_API_KEY) { console.error('TAVILY_API_KEY is not set. Please set it as an environment variable.'); process.exit(1); } const server = new McpServer({ port: DEFAULT_MCP_SERVER_PORT, tavilyApiKey: TAVILY_API_KEY, }); await server.start(); console.log(`Tavily MCP Server started on port ${DEFAULT_MCP_SERVER_PORT}`); try { // Example: Making a search request to the local server const response = await axios.post( `http://localhost:${DEFAULT_MCP_SERVER_PORT}/mcp/`, { tool: 'tavily-search', query: 'latest advancements in AI models' }, { headers: { 'Content-Type': 'application/json' } } ); console.log('Search Results:', JSON.stringify(response.data, null, 2)); } catch (error: any) { console.error('Failed to make request to MCP server:', error.message); if (error.response) { console.error('Server response data:', error.response.data); } } finally { await server.stop(); console.log('Tavily MCP Server stopped.'); } } startAndTestServer();

Debug

Known issues

gotchaWhen connecting to the remote MCP server, ensure your Tavily API key is either passed directly in the URL (`?tavilyApiKey=...`) or via an `Authorization: Bearer <your-api-key>` header. Mixing methods or providing an invalid key will lead to authentication failures.

fix

Always use a single, correct method for API key authentication. For programmatic access, using an Authorization header or environment variable for the API key is recommended.

affects: >=0.1.0

gotchaThe `DEFAULT_PARAMETERS` header, used for setting global defaults on remote MCP requests, must contain a valid JSON string. Malformed JSON will lead to parsing errors on the server side and ignored parameters.

fix

Ensure the `DEFAULT_PARAMETERS` header value is a `stringified` JSON object, e.g., `JSON.stringify({"include_images":true})`.

affects: >=0.1.0

breakingOlder versions might have used different CLI commands or authentication flows for integration with client tools like Claude Code or Cursor. Always refer to the latest documentation for correct integration steps.

fix

Upgrade to the latest `tavily-mcp` version and consult the current README or documentation for updated client integration instructions.

affects: <0.2.0

gotchaWhen running the server locally, ensure that the specified port is not already in use by another application. Port conflicts will prevent the server from starting.

fix

Check for available ports or explicitly configure a different port for the `McpServer` instance if the default `DEFAULT_MCP_SERVER_PORT` (8080) is occupied.

affects: >=0.1.0

Errors

Common errors & fixes

Tavily API Key is missing or invalid

The Tavily API key was not provided or is incorrect, preventing access to Tavily services.

fix

Ensure `TAVILY_API_KEY` is set in your environment variables, passed correctly in the URL (`?tavilyApiKey=...`), or included in the `Authorization: Bearer <key>` header when interacting with the server.

connect ECONNREFUSED 127.0.0.1:8080

The local Tavily MCP server is not running or is listening on a different port than expected.

fix

Verify that `McpServer.start()` was called successfully and the server is actively listening on the configured port (default 8080) before making requests. Check logs for startup errors.

Failed to parse JSON in DEFAULT_PARAMETERS header

The `DEFAULT_PARAMETERS` HTTP header contained a value that could not be parsed as valid JSON.

fix

Ensure the `DEFAULT_PARAMETERS` header value is a properly stringified JSON object, for example, `{"search_depth":"basic"}` should be sent as the string `"{\"search_depth\":\"basic\"}"`.

Upgrade

Version history

0.2.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tavily-ai/tavily-mcp ↗

packagehttps://www.npmjs.com/package/tavily-mcp ↗

homepagehttps://tavily.com ↗