Tavily MCP Server

Instructions

Implementation Reference

• src/index.ts:512-527 (handler)

  Core implementation of the 'tavily-map' tool handler. Posts parameters to the Tavily map API endpoint ('https://api.tavily.com/map'), handles authentication and rate limit errors, and returns the API response containing the site map.
  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:287-343 (schema)

  Input schema for the 'tavily-map' tool, defining parameters such as url (required), max_depth, max_breadth, limit, instructions, filtering options, and categories.
  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 select crawling to specific domains or subdomains (e.g., ^docs\\.example\\.com$)", default: [] }, allow_external: { type: "boolean", description: "Whether to allow following links that go to external domains", default: false }, categories: { type: "array", items: { type: "string", enum: ["Careers", "Blog", "Documentation", "About", "Pricing", "Community", "Developers", "Contact", "Media"] }, description: "Filter URLs using predefined categories like documentation, blog, api, etc", default: [] } }, required: ["url"]
• src/index.ts:284-345 (registration)

  Registration of the 'tavily-map' tool in the ListToolsRequestSchema handler, providing name, description, and input schema.
  { 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 select crawling to specific domains or subdomains (e.g., ^docs\\.example\\.com$)", default: [] }, allow_external: { type: "boolean", description: "Whether to allow following links that go to external domains", default: false }, categories: { type: "array", items: { type: "string", enum: ["Careers", "Blog", "Documentation", "About", "Pricing", "Community", "Developers", "Contact", "Media"] }, description: "Filter URLs using predefined categories like documentation, blog, api, etc", default: [] } }, required: ["url"] } },
• src/index.ts:400-417 (handler)

  Dispatch handler case for 'tavily-map' in the CallToolRequestSchema. Parses arguments, calls the map method, formats the result, and returns the tool response.
  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, categories: Array.isArray(args.categories) ? args.categories : [] }); return { content: [{ type: "text", text: formatMapResults(mapResponse) }] };
• src/index.ts:589-601 (helper)

  Helper function to format the Tavily map API response into a human-readable string listing the base URL and mapped page URLs.
  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'); }