DataForSEO MCP Server

Instructions

Implementation Reference

• src/core/modules/dataforseo-labs/tools/google/competitor-research/google-serp-competitors.tool.ts:81-96 (handler)

  The handle method implements the core tool logic, sending a POST request to the DataForSEO Labs API endpoint for Google SERP competitors with user-provided parameters like keywords, location, and filters.

  async handle(params: any): Promise<any> {
    try {
      const response = await this.client.makeRequest('/v3/dataforseo_labs/google/serp_competitors/live', 'POST', [{
        keywords: params.keywords,
        location_name: params.location_name,
        language_code: params.language_code,
        limit: params.limit,
        offset: params.offset,
        filters: this.formatFilters(params.filters),
        order_by: this.formatOrderBy(params.order_by),
      }]);
      return this.validateAndFormatResponse(response);
    } catch (error) {
      return this.formatErrorResponse(error);
    }
  }

• src/core/modules/dataforseo-labs/tools/google/competitor-research/google-serp-competitors.tool.ts:18-79 (schema)

  Defines the input schema using Zod for parameters such as keywords, location_name, language_code, limit, offset, filters, order_by, and include_subdomains.

    getParams(): z.ZodRawShape {
      return {
        keywords: z.array(z.string()).describe(`keywords array
  required field
  the results will be based on the keywords you specify in this array
  UTF-8 encoding;
  the keywords will be converted to lowercase format;
  you can specify the maximum of 200 keywords`),
        location_name: z.string().default("United States").describe(`full name of the location
  required field
  in format "Country"
  example:
  United Kingdom`),
        language_code: z.string().default("en").describe(
          `language code
          required field
          example:
          en`),
        limit: z.number().min(1).max(1000).default(10).optional().describe("Maximum number of keywords to return"),
        offset: z.number().min(0).optional().describe(
          `offset in the results array of returned keywords
          optional field
          default value: 0
          if you specify the 10 value, the first ten keywords in the results array will be omitted and the data will be provided for the successive keywords`
        ),
        filters: z.array(
          z.union([
            z.array(z.union([z.string(), z.number(), z.boolean()])).length(3),
            z.enum(["and", "or"])
          ])
        ).max(8).optional().describe(
          `you can add several filters at once (8 filters maximum)
          you should set a logical operator and, or between the conditions
          the following operators are supported:
          regex, not_regex, <, <=, >, >=, =, <>, in, not_in, match, not_match, ilike, not_ilike, like, not_like
          you can use the % operator with like and not_like, as well as ilike and not_ilike to match any string of zero or more characters
          merge operator must be a string and connect two other arrays, availible values: or, and.
          example:
          ["ranked_serp_element.serp_item.rank_group","<=",10]
          [["ranked_serp_element.serp_item.rank_group","<=",10],"or",["ranked_serp_element.serp_item.type","<>","paid"]]
          [["keyword_data.keyword_info.search_volume","<>",0],"and",[["ranked_serp_element.serp_item.type","<>","paid"],"or",["ranked_serp_element.serp_item.is_malicious","=",false]]]`
        ),
        order_by: z.array(z.string()).optional().describe(
          `results sorting rules
  optional field
  you can use the same values as in the filters array to sort the results
  possible sorting types:
  asc – results will be sorted in the ascending order
  desc – results will be sorted in the descending order
  the comma is used as a separator
  example:
  ["avg_position,asc"]
  default rule:
  ["rating,desc"]
  note that you can set no more than three sorting rules in a single request
  you should use a comma to separate several sorting rules
  example:
  ["avg_position,asc","etv,desc"]`
        ),
        include_subdomains: z.boolean().optional().describe("Include keywords from subdomains")
      };
    }

• src/core/modules/dataforseo-labs/dataforseo-labs-api.module.ts:29-62 (registration)

  Registers the GoogleSERPCompetitorsTool by instantiating it and including it in the tools array, which is then mapped to a record keyed by tool name (dataforseo_labs_google_serp_competitors).

  getTools(): Record<string, ToolDefinition> {
    const tools = [
      new GoogleRankedKeywordsTool(this.dataForSEOClient),
      new GoogleDomainCompetitorsTool(this.dataForSEOClient),
      new GoogleDomainRankOverviewTool(this.dataForSEOClient),
      new GoogleKeywordsIdeasTool(this.dataForSEOClient),
      new GoogleRelatedKeywordsTool(this.dataForSEOClient),
      new GoogleKeywordsSuggestionsTool(this.dataForSEOClient),
      new GoogleHistoricalSERP(this.dataForSEOClient),
      new GoogleSERPCompetitorsTool(this.dataForSEOClient),
      new GoogleBulkKeywordDifficultyTool(this.dataForSEOClient),
      new GoogleSubdomainsTool(this.dataForSEOClient),
      new GoogleKeywordOverviewTool(this.dataForSEOClient),
      new GoogleTopSearchesTool(this.dataForSEOClient),
      new GoogleSearchIntentTool(this.dataForSEOClient),
      new GoogleKeywordsForSiteTool(this.dataForSEOClient),
      new GoogleDomainIntersectionsTool(this.dataForSEOClient),
      new GoogleHistoricalDomainRankOverviewTool(this.dataForSEOClient),
      new GooglePageIntersectionsTool(this.dataForSEOClient),
      new GoogleBulkTrafficEstimationTool(this.dataForSEOClient),
      new DataForSeoLabsFilterTool(this.dataForSEOClient),
      new GoogleHistoricalKeywordDataTool(this.dataForSEOClient),
      // Add more tools here
    ];
  
    return tools.reduce((acc, tool) => ({
      ...acc,
      [tool.getName()]: {
        description: tool.getDescription(),
        params: tool.getParams(),
        handler: (params: any) => tool.handle(params),
      },
    }), {});
  }

• src/core/modules/dataforseo-labs/tools/labs-filters.tool.ts:24-56 (helper)

  Maps the tool name 'dataforseo_labs_google_serp_competitors' to the filter path 'serp_competitors.google' used in the labs filters tool.

  private static readonly TOOL_TO_FILTER_MAP: { [key: string]: string } = {
    'dataforseo_labs_google_ranked_keywords': 'ranked_keywords.google',
    'dataforseo_labs_google_keyword_ideas': 'keyword_ideas.google',
    'dataforseo_labs_google_keywords_for_site': 'keywords_for_site.google',
    'dataforseo_labs_google_competitors_domain': 'competitors_domain.google',
    'dataforseo_labs_google_serp_competitors': 'serp_competitors.google',
    'dataforseo_labs_google_subdomains': 'subdomains.google',
    'dataforseo_labs_google_domain_intersection': 'domain_intersection.google',
    'dataforseo_labs_google_page_intersection': 'page_intersection.google',
    'dataforseo_labs_google_historical_serp': 'historical_serp.google',
    'dataforseo_labs_google_historical_rank_overview': 'domain_rank_overview.google',
    'dataforseo_labs_google_relevant_pages': 'relevant_pages.google',
    'dataforseo_labs_google_top_searches': 'top_searches.google',
    'dataforseo_labs_google_keyword_overview': 'keyword_overview.google',
    'dataforseo_labs_google_search_intent': 'search_intent.google',
    'dataforseo_labs_google_bulk_keyword_difficulty': 'bulk_keyword_difficulty.google',
    'dataforseo_labs_google_related_keywords': 'related_keywords.google',
    'dataforseo_labs_google_keyword_suggestions': 'keyword_suggestions.google',
    'dataforseo_labs_google_domain_rank_overview': 'domain_rank_overview.google',
    'dataforseo_labs_google_domain_metrics_by_categories': 'domain_metrics_by_categories.google',
    'dataforseo_labs_google_domain_whois_overview': 'domain_whois_overview.google',
    'dataforseo_labs_google_categories_for_domain': 'categories_for_domain.google',
    'dataforseo_labs_google_keywords_for_categories': 'keywords_for_categories.google',
    'dataforseo_labs_amazon_product_competitors': 'product_competitors.amazon',
    'dataforseo_labs_amazon_product_keyword_intersections': 'product_keyword_intersections.amazon',
    'dataforseo_labs_google_app_competitors': 'app_competitors.google',
    'dataforseo_labs_apple_app_competitors': 'app_competitors.apple',
    'dataforseo_labs_google_app_intersection': 'app_intersection.google',
    'dataforseo_labs_apple_app_intersection': 'app_intersection.apple',
    'dataforseo_labs_google_keywords_for_app': 'keywords_for_app.google',
    'dataforseo_labs_apple_keywords_for_app': 'keywords_for_app.apple',
    'dataforseo_labs_database_rows_count': 'database_rows_count'
  };