Tavily MCP Server

Instructions

Implementation Reference

• src/index.ts:355-407 (registration)

  Registers the tavily-map tool including its name, description, and detailed input schema in the ListTools response.
  { name: "tavily-map", description: "A powerful web mapping tool that creates a structured map of website URLs, allowing you to discover and analyze site structure, content organization, and navigation paths. Perfect for site audits, content discovery, and understanding website architecture.", inputSchema: { type: "object", properties: { url: { type: "string", description: "The root URL to begin the mapping" }, max_depth: { type: "integer", description: "Max depth of the mapping. Defines how far from the base URL the crawler can explore", default: 1, minimum: 1 }, max_breadth: { type: "integer", description: "Max number of links to follow per level of the tree (i.e., per page)", default: 20, minimum: 1 }, limit: { type: "integer", description: "Total number of links the crawler will process before stopping", default: 50, minimum: 1 }, instructions: { type: "string", description: "Natural language instructions for the crawler" }, select_paths: { type: "array", items: { type: "string" }, description: "Regex patterns to select only URLs with specific path patterns (e.g., /docs/.*, /api/v1.*)", default: [] }, select_domains: { type: "array", items: { type: "string" }, description: "Regex patterns to restrict crawling to specific domains or subdomains (e.g., ^docs\\.example\\.com$)", default: [] }, allow_external: { type: "boolean", description: "Whether to return external links in the final response", default: true } }, required: ["url"] } },
• src/index.ts:476-492 (handler)

  Main handler for tavily-map tool calls: extracts parameters, invokes the map method, formats response, and returns tool output.
  case "tavily-map": const mapResponse = await this.map({ url: args.url, max_depth: args.max_depth, max_breadth: args.max_breadth, limit: args.limit, instructions: args.instructions, select_paths: Array.isArray(args.select_paths) ? args.select_paths : [], select_domains: Array.isArray(args.select_domains) ? args.select_domains : [], allow_external: args.allow_external }); return { content: [{ type: "text", text: formatMapResults(mapResponse) }] };
• src/index.ts:627-642 (handler)

  Core implementation: sends HTTP POST to Tavily map API endpoint with parameters and handles API errors.
  async map(params: any): Promise<TavilyMapResponse> { try { const response = await this.axiosInstance.post(this.baseURLs.map, { ...params, api_key: API_KEY }); return response.data; } catch (error: any) { if (error.response?.status === 401) { throw new Error('Invalid API key'); } else if (error.response?.status === 429) { throw new Error('Usage limit exceeded'); } throw error; } }
• src/index.ts:50-54 (schema)

  TypeScript interface defining the expected response structure from Tavily map API.
  interface TavilyMapResponse { base_url: string; results: string[]; response_time: number; }
• src/index.ts:710-722 (helper)

  Utility function to format the map API response into readable text output for the tool.
  function formatMapResults(response: TavilyMapResponse): string { const output: string[] = []; output.push(`Site Map Results:`); output.push(`Base URL: ${response.base_url}`); output.push('\nMapped Pages:'); response.results.forEach((page, index) => { output.push(`\n[${index + 1}] URL: ${page}`); }); return output.join('\n'); }