Google Search Console MCP Server

Instructions

Implementation Reference

• src/search-console.ts:74-129 (handler)

  Main handler function implementing the enhanced search analytics tool logic, supporting up to 25k rows, regex filtering, and quick wins detection.
  async enhancedSearchAnalytics( siteUrl: string, requestBody: SearchanalyticsQueryRequest, options: { regexFilter?: string; enableQuickWins?: boolean; quickWinsThresholds?: { minImpressions?: number; maxCtr?: number; positionRangeMin?: number; positionRangeMax?: number; }; } = {} ) { // Ensure requestBody is defined if (!requestBody) { throw new Error('Request body is required'); } // Apply regex filter if provided if (options.regexFilter && requestBody.dimensions?.includes('query')) { requestBody.dimensionFilterGroups = [ ...(requestBody.dimensionFilterGroups || []), { groupType: 'and', filters: [{ dimension: 'query', operator: 'includingRegex', expression: options.regexFilter }] } ]; } // Execute enhanced search analytics const result = await this.searchAnalytics(siteUrl, requestBody); // Apply quick wins detection if enabled if (options.enableQuickWins && result.data.rows) { const quickWins = this.detectQuickWins(result.data.rows, options.quickWinsThresholds); return { ...result, data: { ...result.data, quickWins: quickWins, enhancedFeatures: { regexFilterApplied: !!options.regexFilter, quickWinsEnabled: true, rowLimit: requestBody.rowLimit || 1000 } } }; } return result; }
• src/search-console.ts:135-187 (helper)

  Supporting utility for detecting SEO quick wins based on search analytics data.
  private detectQuickWins( rows: any[], thresholds: { minImpressions?: number; maxCtr?: number; positionRangeMin?: number; positionRangeMax?: number; } = {} ) { const { minImpressions = 50, maxCtr = 2.0, positionRangeMin = 4, positionRangeMax = 10 } = thresholds; return rows .filter(row => { const impressions = row.impressions || 0; const ctr = (row.ctr || 0) * 100; const position = row.position || 0; return impressions >= minImpressions && ctr <= maxCtr && position >= positionRangeMin && position <= positionRangeMax; }) .map(row => { const impressions = row.impressions || 0; const currentClicks = row.clicks || 0; const currentCtr = (row.ctr || 0) * 100; const position = row.position || 0; // Calculate potential with 5% target CTR const targetCtr = 5.0; const potentialClicks = Math.round((impressions * targetCtr) / 100); const additionalClicks = Math.max(0, potentialClicks - currentClicks); return { query: row.keys?.[0] || 'N/A', page: row.keys?.[1] || 'N/A', currentPosition: Number(position.toFixed(1)), impressions: impressions, currentClicks: currentClicks, currentCtr: Number(currentCtr.toFixed(2)), potentialClicks: potentialClicks, additionalClicks: additionalClicks, opportunity: additionalClicks > 0 ? 'High' : 'Low', optimizationNote: `Move from position ${position.toFixed(1)} to improve CTR` }; }) .sort((a, b) => b.additionalClicks - a.additionalClicks); }
• src/schemas.ts:106-117 (schema)

  Zod schema defining inputs for the enhanced_search_analytics tool, extending base search analytics with quick wins options.
  export const EnhancedSearchAnalyticsSchema = SearchAnalyticsSchema.extend({ enableQuickWins: z.boolean().default(false).describe('Enable automatic quick wins detection'), quickWinsThresholds: QuickWinsDetectionSchema.pick({ minImpressions: true, maxCtr: true, positionRangeMin: true, positionRangeMax: true, }).optional().describe('Custom thresholds for quick wins detection'), }); export type SearchAnalytics = z.infer<typeof SearchAnalyticsSchema>; export type EnhancedSearchAnalytics = z.infer<typeof EnhancedSearchAnalyticsSchema>;
• src/index.ts:54-57 (registration)

  Tool registration in MCP server's listTools handler, specifying name, description, and input schema.
  name: 'enhanced_search_analytics', description: 'Enhanced search analytics with up to 25,000 rows, regex filters, and quick wins detection', inputSchema: zodToJsonSchema(EnhancedSearchAnalyticsSchema), },
• src/index.ts:96-161 (handler)

  MCP server handler for calling the enhanced_search_analytics tool, parsing arguments and invoking the service implementation.
  case 'enhanced_search_analytics': { const args = EnhancedSearchAnalyticsSchema.parse(request.params.arguments); const siteUrl = args.siteUrl; // Build enhanced request body const requestBody: any = { startDate: args.startDate, endDate: args.endDate, dimensions: args.dimensions, searchType: args.type, aggregationType: args.aggregationType, rowLimit: args.rowLimit, // Up to 25,000! }; // Build filters (including regex support) const filters = []; if (args.pageFilter) { filters.push({ dimension: 'page', operator: args.filterOperator, expression: args.pageFilter, }); } if (args.queryFilter) { filters.push({ dimension: 'query', operator: args.filterOperator, expression: args.queryFilter, }); } if (args.countryFilter) { filters.push({ dimension: 'country', operator: 'equals', expression: args.countryFilter, }); } if (args.deviceFilter) { filters.push({ dimension: 'device', operator: 'equals', expression: args.deviceFilter, }); } if (filters.length > 0) { requestBody.dimensionFilterGroups = [{ groupType: 'and', filters }]; } // Call enhanced search analytics const enhancedOptions = { regexFilter: args.regexFilter, enableQuickWins: args.enableQuickWins, quickWinsThresholds: args.quickWinsThresholds, }; const response = await searchConsole.enhancedSearchAnalytics(siteUrl, requestBody, enhancedOptions); return { content: [ { type: 'text', text: JSON.stringify(response.data, null, 2), }, ], }; }