{"id":14963,"library":"tavily-mcp","title":"Tavily MCP Server","description":"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.","status":"active","version":"0.2.18","language":"javascript","source_language":"en","source_url":"https://github.com/tavily-ai/tavily-mcp","tags":["javascript","tavily-mcp","tavily","mcp","crawl","model-context-protocol","websearch","claude","claude-desktop"],"install":[{"cmd":"npm install tavily-mcp","lang":"bash","label":"npm"},{"cmd":"yarn add tavily-mcp","lang":"bash","label":"yarn"},{"cmd":"pnpm add tavily-mcp","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Used for programmatic instantiation and management of the local MCP server in TypeScript/ESM projects.","wrong":"const McpServer = require('tavily-mcp').McpServer;","symbol":"McpServer","correct":"import { McpServer } from 'tavily-mcp';"},{"note":"Imports the specific web search tool, often used when integrating individual tools into a custom MCP setup.","wrong":"import TavilySearchTool from 'tavily-mcp/search';","symbol":"TavilySearchTool","correct":"import { TavilySearchTool } from 'tavily-mcp';"},{"note":"Imports the data extraction tool for programmatic use, enabling intelligent parsing of web content.","wrong":"import { extract } from 'tavily-mcp';","symbol":"TavilyExtractTool","correct":"import { TavilyExtractTool } from 'tavily-mcp';"}],"quickstart":{"code":"import { McpServer, DEFAULT_MCP_SERVER_PORT } from 'tavily-mcp';\nimport axios from 'axios';\n\nconst TAVILY_API_KEY = process.env.TAVILY_API_KEY ?? '';\n\nasync function startAndTestServer() {\n  if (!TAVILY_API_KEY) {\n    console.error('TAVILY_API_KEY is not set. Please set it as an environment variable.');\n    process.exit(1);\n  }\n\n  const server = new McpServer({\n    port: DEFAULT_MCP_SERVER_PORT,\n    tavilyApiKey: TAVILY_API_KEY,\n  });\n\n  await server.start();\n  console.log(`Tavily MCP Server started on port ${DEFAULT_MCP_SERVER_PORT}`);\n\n  try {\n    // Example: Making a search request to the local server\n    const response = await axios.post(\n      `http://localhost:${DEFAULT_MCP_SERVER_PORT}/mcp/`, \n      {\n        tool: 'tavily-search',\n        query: 'latest advancements in AI models'\n      },\n      {\n        headers: { 'Content-Type': 'application/json' }\n      }\n    );\n    console.log('Search Results:', JSON.stringify(response.data, null, 2));\n  } catch (error: any) {\n    console.error('Failed to make request to MCP server:', error.message);\n    if (error.response) {\n      console.error('Server response data:', error.response.data);\n    }\n  } finally {\n    await server.stop();\n    console.log('Tavily MCP Server stopped.');\n  }\n}\n\nstartAndTestServer();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure the `DEFAULT_PARAMETERS` header value is a `stringified` JSON object, e.g., `JSON.stringify({\"include_images\":true})`.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade to the latest `tavily-mcp` version and consult the current README or documentation for updated client integration instructions.","message":"Older 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.","severity":"breaking","affected_versions":"<0.2.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The Tavily API key was not provided or is incorrect, preventing access to Tavily services.","error":"Tavily API Key is missing or invalid"},{"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.","cause":"The local Tavily MCP server is not running or is listening on a different port than expected.","error":"connect ECONNREFUSED 127.0.0.1:8080"},{"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\\\"}\"`.","cause":"The `DEFAULT_PARAMETERS` HTTP header contained a value that could not be parsed as valid JSON.","error":"Failed to parse JSON in DEFAULT_PARAMETERS header"}],"ecosystem":"npm"}