Google Search Console MCP Server

Instructions

Implementation Reference

• src/search-console.ts:135-187 (handler)

  Core implementation of quick wins detection: filters low-CTR queries in good positions with sufficient impressions, calculates potential clicks at 5% CTR target, and ranks by opportunity size.
  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:94-103 (schema)

  Zod schema defining input parameters for the detect_quick_wins tool, including date range and customizable thresholds.
  export const QuickWinsDetectionSchema = GSCBaseSchema.extend({ startDate: z.string().describe('Start date in YYYY-MM-DD format'), endDate: z.string().describe('End date in YYYY-MM-DD format'), minImpressions: z.number().default(50).describe('Minimum impressions threshold for quick wins'), maxCtr: z.number().default(2.0).describe('Maximum CTR percentage for quick wins detection'), positionRangeMin: z.number().default(4).describe('Minimum position for quick wins (default: 4)'), positionRangeMax: z.number().default(10).describe('Maximum position for quick wins (default: 10)'), estimatedClickValue: z.number().default(1.0).describe('Estimated value per click for ROI calculation'), conversionRate: z.number().default(0.03).describe('Estimated conversion rate for ROI calculation'), });
• src/index.ts:58-62 (registration)

  Registration of the detect_quick_wins tool in the ListTools response.
  { name: 'detect_quick_wins', description: 'Automatically detect SEO quick wins and optimization opportunities', inputSchema: zodToJsonSchema(QuickWinsDetectionSchema), },
• src/index.ts:163-217 (handler)

  Main tool handler in the CallToolRequest switch statement: fetches search analytics data up to 25k rows and invokes enhanced analysis with quick wins detection enabled.
  case 'detect_quick_wins': { const args = QuickWinsDetectionSchema.parse(request.params.arguments); // First get search analytics data const requestBody: any = { startDate: args.startDate, endDate: args.endDate, dimensions: ['query', 'page'], rowLimit: 25000, // Maximum for comprehensive analysis }; const searchResponse = await searchConsole.searchAnalytics(args.siteUrl, requestBody); if (!searchResponse.data.rows) { return { content: [ { type: 'text', text: JSON.stringify({ message: 'No data available for quick wins analysis' }, null, 2), }, ], }; } // Apply quick wins detection const quickWinsOptions = { enableQuickWins: true, quickWinsThresholds: { minImpressions: args.minImpressions, maxCtr: args.maxCtr, positionRangeMin: args.positionRangeMin, positionRangeMax: args.positionRangeMax, }, }; const enhancedResult = await searchConsole.enhancedSearchAnalytics( args.siteUrl, requestBody, quickWinsOptions ); return { content: [ { type: 'text', text: JSON.stringify({ quickWins: (enhancedResult.data as any).quickWins, totalOpportunities: (enhancedResult.data as any).quickWins?.length || 0, thresholds: quickWinsOptions.quickWinsThresholds, analysis: 'Quick wins detection completed' }, null, 2), }, ], }; }
• src/search-console.ts:74-129 (helper)

  Supporting method that applies quick wins detection (and regex filtering) to search analytics results, invoked by the main tool handler.
  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; }