tavily-mcp

Instructions

Implementation Reference

• src/index.ts:455-477 (handler)

  The core implementation of the tavily-search tool: makes HTTP POST request to Tavily's search API endpoint with the provided search parameters, handles topic inference for news queries, and manages API errors like invalid key or rate limits.

  async search(params: any): Promise<TavilyResponse> {
    try {
      // Choose endpoint based on whether it's an extract request
      const endpoint = params.url ? this.baseURLs.extract : this.baseURLs.search;
      
      // Add topic: "news" if query contains the word "news"
      const searchParams = {
        ...params,
        api_key: API_KEY,
        topic: params.query.toLowerCase().includes('news') ? 'news' : undefined
      };
      
      const response = await this.axiosInstance.post(endpoint, searchParams);
      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:115-188 (schema)

  JSON schema defining the input parameters for the tavily-search tool, including query, search depth, topic, time filters, result limits, image inclusion, and domain filtering.

  inputSchema: {
    type: "object",
    properties: {
      query: { 
        type: "string", 
        description: "Search query" 
      },
      search_depth: {
        type: "string",
        enum: ["basic","advanced"],
        description: "The depth of the search. It can be 'basic' or 'advanced'",
        default: "basic"
      },
      topic : {
        type: "string",
        enum: ["general","news"],
        description: "The category of the search. This will determine which of our agents will be used for the search",
        default: "general"
      },
      days: {
        type: "number",
        description: "The number of days back from the current date to include in the search results. This specifies the time frame of data to be retrieved. Please note that this feature is only available when using the 'news' search topic",
        default: 3
      },
      time_range: {
        type: "string",
        description: "The time range back from the current date to include in the search results. This feature is available for both 'general' and 'news' search topics",
        enum: ["day", "week", "month", "year", "d", "w", "m", "y"],
      },
      max_results: { 
        type: "number", 
        description: "The maximum number of search results to return",
        default: 10,
        minimum: 5,
        maximum: 20
      },
      include_images: { 
        type: "boolean", 
        description: "Include a list of query-related images in the response",
        default: false,
      },
      include_image_descriptions: { 
        type: "boolean", 
        description: "Include a list of query-related images and their descriptions in the response",
        default: false,
      },
      /*
      // Since the mcp server is using AI clients to generate answers form the search results, we don't need to include this feature.
      include_answer: { 
        type: ["boolean", "string"],
        enum: [true, false, "basic", "advanced"],
        description: "Include an answer to original query, generated by an LLM based on Tavily's search results. Can be boolean or string ('basic'/'advanced'). 'basic'/true answer will be quick but less detailed, 'advanced' answer will be more detailed but take longer to generate",
        default: false,
      },
      */
      include_raw_content: { 
        type: "boolean", 
        description: "Include the cleaned and parsed HTML content of each search result",
        default: false,
      },
      include_domains: {
        type: "array",
        items: { type: "string" },
        description: "A list of domains to specifically include in the search results, if the user asks to search on specific sites set this to the domain of the site",
        default: []
      },
      exclude_domains: {
        type: "array",
        items: { type: "string" },
        description: "List of domains to specifically exclude, if the user asks to exclude a domain set this to the domain of the site",
        default: []
      }
    },
    required: ["query"]

• src/index.ts:357-371 (registration)

  Dispatch case in the CallToolRequestSchema handler that maps tavily-search tool invocation to the search method with parsed arguments.

  case "tavily-search":
    response = await this.search({
      query: args.query,
      search_depth: args.search_depth,
      topic: args.topic,
      days: args.days,
      time_range: args.time_range,
      max_results: args.max_results,
      include_images: args.include_images,
      include_image_descriptions: args.include_image_descriptions,
      include_raw_content: args.include_raw_content,
      include_domains: Array.isArray(args.include_domains) ? args.include_domains : [],
      exclude_domains: Array.isArray(args.exclude_domains) ? args.exclude_domains : []
    });
    break;

• src/index.ts:112-190 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and schema for tavily-search.

  {
    name: "tavily-search",
    description: "A powerful web search tool that provides comprehensive, real-time results using Tavily's AI search engine. Returns relevant web content with customizable parameters for result count, content type, and domain filtering. Ideal for gathering current information, news, and detailed web content analysis.",
    inputSchema: {
      type: "object",
      properties: {
        query: { 
          type: "string", 
          description: "Search query" 
        },
        search_depth: {
          type: "string",
          enum: ["basic","advanced"],
          description: "The depth of the search. It can be 'basic' or 'advanced'",
          default: "basic"
        },
        topic : {
          type: "string",
          enum: ["general","news"],
          description: "The category of the search. This will determine which of our agents will be used for the search",
          default: "general"
        },
        days: {
          type: "number",
          description: "The number of days back from the current date to include in the search results. This specifies the time frame of data to be retrieved. Please note that this feature is only available when using the 'news' search topic",
          default: 3
        },
        time_range: {
          type: "string",
          description: "The time range back from the current date to include in the search results. This feature is available for both 'general' and 'news' search topics",
          enum: ["day", "week", "month", "year", "d", "w", "m", "y"],
        },
        max_results: { 
          type: "number", 
          description: "The maximum number of search results to return",
          default: 10,
          minimum: 5,
          maximum: 20
        },
        include_images: { 
          type: "boolean", 
          description: "Include a list of query-related images in the response",
          default: false,
        },
        include_image_descriptions: { 
          type: "boolean", 
          description: "Include a list of query-related images and their descriptions in the response",
          default: false,
        },
        /*
        // Since the mcp server is using AI clients to generate answers form the search results, we don't need to include this feature.
        include_answer: { 
          type: ["boolean", "string"],
          enum: [true, false, "basic", "advanced"],
          description: "Include an answer to original query, generated by an LLM based on Tavily's search results. Can be boolean or string ('basic'/'advanced'). 'basic'/true answer will be quick but less detailed, 'advanced' answer will be more detailed but take longer to generate",
          default: false,
        },
        */
        include_raw_content: { 
          type: "boolean", 
          description: "Include the cleaned and parsed HTML content of each search result",
          default: false,
        },
        include_domains: {
          type: "array",
          items: { type: "string" },
          description: "A list of domains to specifically include in the search results, if the user asks to search on specific sites set this to the domain of the site",
          default: []
        },
        exclude_domains: {
          type: "array",
          items: { type: "string" },
          description: "List of domains to specifically exclude, if the user asks to exclude a domain set this to the domain of the site",
          default: []
        }
      },
      required: ["query"]
    }
  },

• src/index.ts:531-567 (helper)

  Helper function to format the Tavily search response into a human-readable text string for the tool output.

  function formatResults(response: TavilyResponse): string {
    // Format API response into human-readable text
    const output: string[] = [];
  
    // Include answer if available
    if (response.answer) {
      output.push(`Answer: ${response.answer}`);
    }
  
    // Format detailed search results
    output.push('Detailed Results:');
    response.results.forEach(result => {
      output.push(`\nTitle: ${result.title}`);
      output.push(`URL: ${result.url}`);
      output.push(`Content: ${result.content}`);
      if (result.raw_content) {
        output.push(`Raw Content: ${result.raw_content}`);
      }
    });
  
      // Add images section if available
      if (response.images && response.images.length > 0) {
        output.push('\nImages:');
        response.images.forEach((image, index) => {
          if (typeof image === 'string') {
            output.push(`\n[${index + 1}] URL: ${image}`);
          } else {
            output.push(`\n[${index + 1}] URL: ${image.url}`);
            if (image.description) {
              output.push(`   Description: ${image.description}`);
            }
          }
        });
      }  
  
    return output.join('\n');
  }