search_analytics
Retrieve and analyze search performance data from Google Search Console to understand website visibility, traffic patterns, and optimize content strategy.
Instructions
Get search performance data from Google Search Console
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | The site URL as defined in Search Console. Example: sc-domain:example.com (for domain resources) or http://www.example.com/ (for site prefix resources) | |
| startDate | Yes | Start date in YYYY-MM-DD format | |
| endDate | Yes | End date in YYYY-MM-DD format | |
| dimensions | No | Comma-separated list of dimensions to break down results by, such as query, page, country, device, searchAppearance | |
| type | No | Type of search to filter by, such as web, image, video, news | |
| aggregationType | No | Type of aggregation, such as auto, byNewsShowcasePanel, byProperty, byPage | |
| rowLimit | No | Maximum number of rows to return (up to 25,000 for enhanced performance) | |
| pageFilter | No | Filter by a specific page URL. Use with filterOperator. | |
| queryFilter | No | Filter by a specific query string. Use with filterOperator. | |
| countryFilter | No | Filter by a country using ISO 3166-1 alpha-3 code (e.g., USA, CHN). | |
| deviceFilter | No | Filter by device type. | |
| filterOperator | No | Operator for page and query filters. Defaults to "equals". Enhanced with regex support. | equals |
| regexFilter | No | Advanced regex filter for intelligent query matching |
Implementation Reference
- src/search-console.ts:60-66 (handler)Core handler function that executes the Google Search Console search analytics API query, handling site URL normalization and permissions.async searchAnalytics(siteUrl: string, requestBody: SearchanalyticsQueryRequest) { const webmasters = await this.getWebmasters(); return this.handlePermissionError( () => webmasters.searchanalytics.query({ siteUrl, requestBody }), () => webmasters.searchanalytics.query({ siteUrl: this.normalizeUrl(siteUrl), requestBody }), ); }
- src/index.ts:219-277 (handler)MCP tool call handler for 'search_analytics' that validates input with schema, builds the API request body with filters, calls SearchConsoleService.searchAnalytics, and formats the response.case 'search_analytics': { const args = SearchAnalyticsSchema.parse(request.params.arguments); const siteUrl = args.siteUrl; // --- 动态构建请求体 --- const requestBody: any = { startDate: args.startDate, endDate: args.endDate, dimensions: args.dimensions, searchType: args.type, aggregationType: args.aggregationType, rowLimit: args.rowLimit, }; 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', // Country filter only supports 'equals' expression: args.countryFilter, }); } if (args.deviceFilter) { filters.push({ dimension: 'device', operator: 'equals', // Device filter only supports 'equals' expression: args.deviceFilter, }); } if (filters.length > 0) { requestBody.dimensionFilterGroups = [{ filters }]; } // --- 构建结束 --- const response = await searchConsole.searchAnalytics(siteUrl, requestBody); return { content: [ { type: 'text', text: JSON.stringify(response.data, null, 2), }, ], }; }
- src/schemas.ts:11-43 (schema)Zod schema defining the input parameters for the search_analytics tool, including dates, dimensions, filters, and validation.export const SearchAnalyticsSchema = GSCBaseSchema.extend({ startDate: z.string().describe('Start date in YYYY-MM-DD format'), endDate: z.string().describe('End date in YYYY-MM-DD format'), dimensions: z .string() .transform((val) => val.split(',')) .refine((val) => val.every((d) => ['query', 'page', 'country', 'device', 'searchAppearance'].includes(d)), ) .optional() .describe( 'Comma-separated list of dimensions to break down results by, such as query, page, country, device, searchAppearance', ), type: z .enum(['web', 'image', 'video', 'news']) .optional() .describe('Type of search to filter by, such as web, image, video, news'), aggregationType: z .enum(['auto', 'byNewsShowcasePanel', 'byProperty', 'byPage']) .optional() .describe('Type of aggregation, such as auto, byNewsShowcasePanel, byProperty, byPage'), rowLimit: z.number().min(1).max(25000).default(1000).describe('Maximum number of rows to return (up to 25,000 for enhanced performance)'), pageFilter: z.string().optional().describe('Filter by a specific page URL. Use with filterOperator.'), queryFilter: z.string().optional().describe('Filter by a specific query string. Use with filterOperator.'), countryFilter: z.string().optional().describe('Filter by a country using ISO 3166-1 alpha-3 code (e.g., USA, CHN).'), deviceFilter: z.enum(['DESKTOP', 'MOBILE', 'TABLET']).optional().describe('Filter by device type.'), filterOperator: z .enum(['equals', 'contains', 'notEquals', 'notContains', 'includingRegex', 'excludingRegex']) .default('equals') .optional() .describe('Operator for page and query filters. Defaults to "equals". Enhanced with regex support.'), regexFilter: z.string().optional().describe('Advanced regex filter for intelligent query matching'), });
- src/index.ts:48-52 (registration)Registration of the search_analytics tool in the list_tools handler, providing name, description, and input schema.{ name: 'search_analytics', description: 'Get search performance data from Google Search Console', inputSchema: zodToJsonSchema(SearchAnalyticsSchema), },