Run a full SEO audit on your site using Claude and your real Google Search Console data.
Connect this MCP server, get your GSC seo data, and ask Claude to find your content decay, cannibalisation, striking distance keywords, CTR problems, and growth opportunities. Claude analyses your complete dataset — not the 1,000-row sample the API normally returns — and gives you prioritised, actionable recommendations. Just like a good seo consultant.
Navigation
How to audit your site | Quick start | vs SEOgets | Tools | Custom SQL | Data retention | Development
Once you've installed the server (quick start below), here's how to run a proper SEO audit using conversation with Claude. Each prompt targets a specific audit area, and Claude will query your full dataset to answer.
Start broad. Ask Claude to show you the dashboard, then follow up:
"Show me my search console data for the last 3 months"
"What's my overall trajectory? Are clicks and impressions trending up or down?"
These are queries where you're ranking 5-20 with decent impressions — close to page one but not there yet. Small improvements here deliver outsized returns.
"Find queries where I'm ranking between position 5 and 20 with more than 500 impressions. Which pages are these on and what would it take to push them to page one?"
Pages that were performing well but are now losing traffic. Catch these early before they fall further.
"Which pages have lost the most clicks compared to the previous period? Focus on pages that had at least 50 clicks before."
"For my top 5 declining pages, what queries are they losing rankings on?"
High impressions with low CTR means your title tags and meta descriptions aren't compelling enough, or there's a SERP feature stealing the click.
"Show me pages with more than 10,000 impressions but CTR below 2%. What's the average position for each?"
"For these low-CTR pages, suggest better title tags based on the queries driving impressions."
Multiple pages competing for the same query splits your ranking signal.
"Find queries where more than one page is ranking. Sort by total clicks so I can see which cannibalisation is actually costing me traffic."
Queries that just appeared in your data — you're starting to rank for something new.
"What new queries appeared this month that I wasn't ranking for last month? Which ones have the most impressions?"
"Compare my mobile vs desktop CTR for my top 20 pages. Are there pages where mobile is significantly worse?"
"Which countries am I getting impressions from but almost no clicks? Is there a localisation opportunity?"
"Based on everything you can see in my search console data, give me a prioritised list of the top 5 things I should work on this month to grow organic traffic."
Claude analyses the full dataset and returns prioritised, specific recommendations:
Related MCP server: seoagent
This project was inspired by SEOgets, which is an excellent GSC analytics platform. If you want a polished, hosted UI with content grouping and topic clustering, check them out — they're worth the $49/month for teams that need a production dashboard.
That said, this MCP server exists because we wanted something different: an AI-native workflow where Claude directly queries your data and gives you recommendations, not just charts.
Here's an honest comparison:
Feature | Better Search Console | |
Price | Free, open source | $49/month |
Row limit | None (full pagination) | 50,000 rows |
Data storage | Local SQLite, unlimited retention | Cloud-hosted |
AI analysis | Claude queries your data directly, gives recommendations | No LLM integration |
Custom SQL | Full SQL access to raw data | No |
Content grouping | No (ask Claude to group by pattern) | Yes, one-click |
Topic clustering | No (ask Claude to cluster) | Yes, one-click |
Cannibalisation report | Yes (via SQL or ask Claude) | Yes, built-in |
Striking distance | Yes (built-in insight) | Yes, built-in |
Content decay | Yes (via SQL or ask Claude) | Yes, heatmap |
Index monitoring | No | Yes, up to 5,000 pages |
Shareable reports | No | Yes, client portal |
SEO testing | No | Yes, built-in |
Multi-user | No | Yes, unlimited users |
Hosting | Self-hosted (your machine) | Fully hosted |
Where SEOgets wins: Content grouping, topic clustering, index monitoring, shareable client portals, SEO testing, and a polished hosted UI that doesn't require any setup beyond OAuth. If you're an agency sending reports to clients, SEOgets is the better choice.
Where Better Search Console wins: No row limits (we sync everything, not 50K rows), direct AI analysis with actionable recommendations, full SQL access to raw data, completely free, and your data never leaves your machine. If you want Claude to audit your site and tell you what to fix, this is what it's built for.
They solve different problems. Use both if you want.
You need a Google Cloud service account with Search Console API access.
Go to the Google Cloud Console
Create a new project (or select an existing one)
Go to APIs and Services > Library
Search for Google Search Console API and click Enable
Go to APIs and Services > Credentials
Click Create Credentials > Service account
Give it a name (e.g. search-console-mcp) and click Create and Continue
Skip the optional role and user access steps, click Done
Click on the service account you just created
Go to the Keys tab
Click Add Key > Create new key > JSON
Save the downloaded JSON file somewhere safe (e.g. ~/credentials/gsc-service-account.json)
For full details, see the Google Workspace credentials guide.
Open the JSON key file and copy the client_email value
Go to Google Search Console
Select a property
Go to Settings > Users and permissions > Add user
Paste the service account email and set permission to Full
Repeat for each property you want to access
Add this to your Claude Desktop config file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"better-search-console": {
"command": "npx",
"args": ["-y", "@houtini/better-search-console"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your-service-account.json"
}
}
}
}claude mcp add \
-e GOOGLE_APPLICATION_CREDENTIALS=/path/to/your-service-account.json \
-s user \
better-search-console -- npx -y @houtini/better-search-consoleVerify with claude mcp get better-search-console — you should see Status: Connected.
Tell Claude: "Show me my search console data"
The setup tool discovers your properties, syncs them in the background, and shows an overview. Initial sync takes 30 seconds to a few minutes depending on data volume. Then follow the audit guide above.
Variable | Required | Default | Description |
| Yes | — | Path to the service account JSON key file |
| No |
| Where SQLite databases are stored |
Tool | Description |
| First-run experience. Lists properties, syncs all, returns overview |
| Sync a single property. Full pagination, no row limits |
| Sync every accessible property (up to 2 in parallel) |
| Poll sync progress. Omit job ID to see all jobs |
| Stop a running sync |
Tool | Description |
| All properties at a glance with sparkline trends |
| Deep dive: metrics, trend chart, top queries/pages, countries, ranking distribution, new/lost queries, branded split |
| 16 pre-built analytical queries (see below) |
| Compare two date ranges across any dimension |
| Run any SELECT query against the raw data |
| Apply data retention policy (preview mode available) |
Insight | Description |
| Aggregate metrics with period-over-period changes |
| Highest-traffic queries |
| Highest-traffic pages |
| Queries gaining or losing clicks |
| Pages gaining or losing clicks |
| Queries ranking 5-20 with high impressions — your quick wins |
| Desktop vs mobile vs tablet |
| Traffic by country |
| Queries for a page, or pages for a query |
| Day-by-day metrics |
| Queries that appeared or disappeared |
| Branded vs non-branded traffic |
The interactive dashboards are built with Chart.js and Vite, bundled into self-contained HTML files using vite-plugin-singlefile, and served via the MCP ext-apps protocol as embedded iframes in Claude Desktop.
Features include metric toggles (clicks, impressions, CTR, position), period comparison with dashed overlays, regex query/page filtering, date range presets, and automatic light/dark theme. Site logos load dynamically via logo.dev.
If your MCP client doesn't support ext-apps, all tools return structured data that Claude can analyse in text.
The query_gsc_data tool accepts any SELECT against the search_analytics table:
search_analytics (
date TEXT, -- YYYY-MM-DD
query TEXT,
page TEXT,
device TEXT, -- DESKTOP, MOBILE, TABLET
country TEXT, -- ISO 3166-1 alpha-3 lowercase
clicks INTEGER,
impressions INTEGER,
ctr REAL,
position REAL
)Find cannibalisation:
SELECT query, COUNT(DISTINCT page) as pages, SUM(clicks) as clicks
FROM search_analytics
WHERE date >= '2025-01-01'
GROUP BY query HAVING pages > 1
ORDER BY clicks DESC LIMIT 20Content decay detection:
SELECT page,
SUM(CASE WHEN date >= date('now', '-28 days') THEN clicks END) as recent,
SUM(CASE WHEN date BETWEEN date('now', '-56 days') AND date('now', '-29 days') THEN clicks END) as prior
FROM search_analytics
GROUP BY page HAVING prior > 10
ORDER BY (recent * 1.0 / NULLIF(prior, 0)) ASC LIMIT 20Large properties generate millions of rows. The retention system prunes automatically after each sync:
Recent data (last 90 days) is never touched
Target countries (US, UK, EU, AU, CA): zero-click rows kept only if 5+ impressions
Non-target countries: zero-click rows deleted entirely
Rows with clicks are never deleted
On a 9.8M row database, initial prune removed 6.3M rows (64%), reduced size from 6GB to 2.2GB, and preserved every click.
Run manually with prune_database (use preview=true to see what would be deleted first).
git clone https://github.com/houtini-ai/better-search-console.git
cd better-search-console
npm install
npm run buildCommand | Description |
| Build everything (server + UI bundles) |
| TypeScript compilation only |
| Vite builds for all three UI views |
| Watch mode for server TypeScript |
| Run the compiled server |
"No Google Search Console properties found" — The service account needs to be added as a user on each property in Search Console > Settings > Users and permissions.
Sync takes a long time — Large properties with years of data can have millions of rows. Initial sync for 10M rows takes 5-10 minutes. Subsequent syncs are incremental.
ext-apps UI not rendering — The dashboards require Claude Desktop with ext-apps support. Text-based fallback responses still contain all the data.
Apache-2.0. See LICENSE for details.
Built by Houtini for the Model Context Protocol community. Inspired by the excellent SEOgets.
Cancel a running sync job. The job will stop gracefully after completing the current API call.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | Job ID to cancel. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior ('stop gracefully after completing the current API call'), which clarifies that it's a controlled termination rather than an abrupt halt. However, it doesn't mention potential side effects, error conditions, or what happens if the job is already completed, leaving some behavioral aspects uncovered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, consisting of two clear sentences that directly state the purpose and behavior without any wasted words. Every sentence earns its place by providing essential information, making it highly efficient and well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation operation with no annotations and no output schema), the description is minimally complete. It covers the basic action and behavior but lacks details on error handling, return values, or integration with sibling tools. For a tool that modifies system state, more context would be beneficial, but it meets the minimum viable threshold.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the jobId parameter fully documented in the input schema. The description doesn't add any additional meaning or context beyond what the schema provides (e.g., format examples or source of the jobId). Since the schema handles the parameter documentation adequately, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Cancel a running sync job') and resource ('sync job'), distinguishing it from sibling tools like check_sync_status or sync_all_properties. It provides a precise verb+resource combination that leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a sync job is running and needs to be stopped, but it doesn't explicitly state when to use this tool versus alternatives like prune_database or when not to use it (e.g., for non-running jobs). There's no mention of prerequisites or comparisons with other tools, leaving usage context partially inferred rather than explicitly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the status of a background sync job. If no jobId provided, returns all active and recent jobs. Use after sync_gsc_data or sync_all_properties to monitor progress.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | No | Job ID from sync_gsc_data or sync_all_properties. Omit to see all jobs. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool can return status for a specific job or all jobs, which is useful behavioral context. However, it doesn't mention error handling, response format, or what 'recent' means (timeframe).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. First sentence states purpose and parameter behavior, second provides usage guidance. Every sentence earns its place with essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 1 parameter with full schema coverage and no output schema, the description is reasonably complete. It covers purpose, parameter semantics, and usage context. However, without annotations or output schema, it could benefit from more detail on response format or error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the semantics of omitting the parameter ('If no jobId provided, returns all active and recent jobs') and specifying where jobId comes from ('from sync_gsc_data or sync_all_properties'), which goes beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('check') and resource ('status of a background sync job'), and distinguishes from siblings by specifying it's for monitoring jobs from sync_gsc_data or sync_all_properties. It's specific about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('Use after sync_gsc_data or sync_all_properties to monitor progress') and provides an alternative usage pattern ('If no jobId provided, returns all active and recent jobs'). This gives clear guidance on when and how to invoke the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two arbitrary date ranges side-by-side across any dimension (query, page, device, country). Shows absolute and percentage changes. Useful for before/after analysis, seasonal comparisons, or measuring the impact of changes. Requires synced data — run setup first if needed.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | GSC property URL. | |
| period1Start | Yes | Period 1 start date (YYYY-MM-DD). | |
| period1End | Yes | Period 1 end date (YYYY-MM-DD). | |
| period2Start | Yes | Period 2 start date (YYYY-MM-DD). | |
| period2End | Yes | Period 2 end date (YYYY-MM-DD). | |
| dimension | No | Dimension to group by. Default: "query". | |
| limit | No | Max rows. Default: 50. | |
| pageFilter | No | Filter by URL path (uses LIKE). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context about the tool's output ('Shows absolute and percentage changes') and data requirements ('Requires synced data'), but does not cover other behavioral aspects like error handling, performance characteristics, or authentication needs, leaving gaps for a tool with 8 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with the first sentence stating the core functionality, followed by supporting details about output and prerequisites. Every sentence earns its place by adding distinct value without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, no output schema, no annotations), the description is reasonably complete for a comparative analysis tool. It covers purpose, usage context, output format, and prerequisites, though it could benefit from more behavioral details or examples to fully compensate for the lack of annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal value beyond the schema by implying the tool's purpose involves date ranges and dimensions, but does not provide additional syntax, format details, or usage examples for parameters beyond what the schema specifies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('compare two arbitrary date ranges side-by-side') and resources ('across any dimension'), distinguishing it from siblings like 'query_gsc_data' or 'get_insights' by focusing on comparative analysis rather than raw data retrieval or general insights.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool ('before/after analysis, seasonal comparisons, or measuring the impact of changes') and includes a prerequisite ('Requires synced data — run setup first if needed'). However, it does not explicitly state when not to use it or name specific alternatives among the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Drill into a single property. Shows an interactive dashboard with hero metrics, trend chart, top queries, top pages, country breakdown, ranking distribution, new/lost queries, and branded split. Use the siteUrl from get_overview results. Requires synced data — run setup first if needed.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | GSC property URL, e.g. "sc-domain:example.com". Get this from the overview or list_properties. | |
| dateRange | No | Date range: "7d", "28d", "3m", "6m", "12m", "16m", or named presets: "lw", "tm", "lm", "tq", "lq", "ytd". Default: "3m". | |
| comparisonMode | No | Comparison mode. Default: "previous_period". | |
| matchWeekdays | No | Align comparison period to match weekday patterns. Default: false. | |
| brandTerms | No | Brand terms for branded/non-branded split (e.g. ["mysite", "my site"]). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it shows an 'interactive dashboard' (output format), requires 'synced data' (prerequisite state), and has dependencies on other tools ('run setup first if needed'). It doesn't mention error conditions or performance characteristics, but covers essential operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise: first sentence states purpose, second enumerates dashboard components, third provides usage guidance, fourth states prerequisites. Every sentence earns its place with no wasted words, and critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no annotations, and no output schema, the description does well by explaining the dashboard's interactive nature and components. It covers prerequisites and tool relationships adequately. The main gap is lack of output format details - while it mentions 'interactive dashboard', it doesn't describe the return structure or data format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 5 parameters thoroughly. The description adds minimal parameter semantics beyond the schema - it mentions 'siteUrl from get_overview results' which provides sourcing context, but doesn't add significant meaning about parameter usage or interactions beyond what's in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('drill into', 'shows') and resources ('a single property', 'interactive dashboard'). It distinguishes from siblings by specifying this is for detailed property-level analysis rather than overview or list operations, and mentions specific dashboard components like hero metrics and trend charts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Drill into a single property' indicates it's for detailed analysis after broader overviews. It specifies prerequisites: 'Use the siteUrl from get_overview results' and 'Requires synced data — run setup first if needed', clearly differentiating from setup and overview tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run pre-built analytical queries against synced GSC data. Choose from 16 insight types: summary, top_queries, top_pages, growing_queries, declining_queries, growing_pages, declining_pages, opportunities (queries ranking 5-20 with high impressions — your quick wins), device_breakdown, country_breakdown, page_queries, query_pages, daily_trend, new_queries, lost_queries, branded_split. Requires synced data — run setup first if needed.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | GSC property URL. | |
| insight | Yes | Insight type to run. | |
| dateRange | No | Date range: "7d", "28d", "3m", "6m", "12m", "16m". Default: "28d". | |
| pageFilter | No | Filter by URL path (uses LIKE). e.g. "/blog/" | |
| queryFilter | No | Filter by query text (uses LIKE). | |
| device | No | Filter by device: DESKTOP, MOBILE, TABLET. | |
| country | No | Filter by ISO country code. | |
| brandTerms | No | Brand terms for branded_split insight. | |
| limit | No | Max rows returned. Default: 50. | |
| minClicks | No | Minimum clicks threshold. | |
| minImpressions | No | Minimum impressions threshold. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the prerequisite (synced data) which is crucial context, but doesn't describe other important behaviors: whether this is a read-only operation, what the output format looks like (tabular data? JSON structure?), whether there are rate limits, or what happens with large result sets. The description adds some value but leaves significant behavioral aspects unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: it starts with the core purpose, immediately lists all insight types (essential information), provides helpful parenthetical explanations for key insights like 'opportunities', and ends with the critical prerequisite. Every sentence earns its place, and the information is front-loaded with the most important details first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 parameters, no output schema, no annotations), the description is incomplete. While it covers the purpose, insight types, and prerequisite well, it doesn't address the output format, result limitations, or behavioral characteristics needed for a tool with this many parameters and analytical complexity. The agent would need to guess about the return structure and operational constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents all 11 parameters thoroughly. The description adds minimal parameter semantics beyond the schema - it lists the 16 insight types (which the enum already contains) and briefly explains the 'opportunities' insight. However, it doesn't provide additional context about parameter interactions or usage patterns that would help the agent beyond what's in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Run pre-built analytical queries against synced GSC data.' It specifies the verb ('run'), resource ('pre-built analytical queries'), and target data ('synced GSC data'). It also lists all 16 insight types, providing specific differentiation from sibling tools like 'query_gsc_data' (which likely runs custom queries) and 'get_overview' (which might provide general metrics).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Requires synced data — run setup first if needed.' This tells the agent when NOT to use this tool (if data isn't synced) and what alternative to use first ('setup'). It also implies this tool is for analytical insights rather than raw data queries, distinguishing it from siblings like 'query_gsc_data'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
See all your sites at a glance. Shows an interactive grid of every synced GSC property with clicks, impressions, CTR, position, percentage changes, and sparkline trends. Click any property card to open its full dashboard. If no data appears, run setup first to sync your properties.
| Name | Required | Description | Default |
|---|---|---|---|
| dateRange | No | Date range: "7d", "28d", "3m", "6m", "12m", "16m". Default: "28d". | |
| sortBy | No | Sort order for property cards. Default: "alpha". | |
| search | No | Filter properties by domain name substring. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the output format ('interactive grid') and includes a prerequisite action ('run setup first'), which adds useful context. However, it doesn't cover other behavioral aspects like whether this is a read-only operation, performance characteristics, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose in the first sentence, followed by additional details in a logical flow. Every sentence earns its place by explaining features, interaction, and prerequisites without redundancy. It's appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (3 parameters, no output schema, no annotations), the description is mostly complete. It explains what the tool does, the output format, and a prerequisite. However, it could improve by mentioning the tool's read-only nature or linking to sibling tools for related actions, which would enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, such as explaining how 'search' interacts with the grid or default behaviors. This meets the baseline of 3 when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('see', 'shows') and resources ('all your sites', 'every synced GSC property'). It distinguishes from siblings like 'list_properties' by specifying it shows an interactive grid with detailed metrics (clicks, impressions, CTR, etc.) and trends, rather than just listing properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('see all your sites at a glance') and includes a prerequisite ('If no data appears, run setup first to sync your properties'). However, it doesn't explicitly state when not to use it or name alternatives among siblings, such as 'get_dashboard' for individual property details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Google Search Console properties accessible via the service account, with permission level and local sync status. Usually not needed — setup handles this automatically.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that the tool lists properties 'accessible via the service account' (implying authentication needs) and includes 'permission level and local sync status' in the output, which adds useful context beyond a basic list. However, it doesn't cover potential rate limits, error conditions, or response format details, leaving some behavioral aspects unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured: two sentences that efficiently convey the tool's purpose and usage guidance. Every word earns its place, with no redundancy or unnecessary details, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is reasonably complete. It explains what the tool does, what information it returns, and when to use it. However, without an output schema, it could benefit from more detail on the response structure (e.g., format of 'permission level' and 'sync status'), though the lack of complexity keeps this from being a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100% (since there are no parameters to describe). The description doesn't need to add parameter semantics, so a baseline score of 4 is appropriate. It correctly implies no inputs are required, aligning with the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'List all Google Search Console properties accessible via the service account, with permission level and local sync status.' This specifies the verb ('List'), resource ('Google Search Console properties'), and key output details. However, it doesn't explicitly differentiate from sibling tools like 'sync_all_properties' or 'check_sync_status' beyond mentioning 'local sync status'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Usually not needed — setup handles this automatically.' This clearly indicates that the tool is primarily for debugging or manual checks rather than routine operations, helping the agent avoid unnecessary invocations. No alternatives are named, but the context is sufficient for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply data retention policy to a synced property database. Removes low-value rows (zero clicks, low impressions) from older data while preserving all recent data and actionable historical data. Runs VACUUM afterwards to reclaim disk space. This runs automatically after each sync, but you can also trigger it manually. Use preview_prune first to see what would be deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | GSC property URL to prune. | |
| recentDays | No | Days of recent data to keep in full (default: 90). | |
| targetMinImpressions | No | For target countries: min impressions to keep zero-click rows (default: 5). | |
| preview | No | If true, show what would be deleted without actually deleting. Default: false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it removes low-value rows based on specific criteria (zero clicks, low impressions), preserves recent and actionable data, runs VACUUM to reclaim disk space, and mentions the automatic execution after syncs. However, it lacks details on permissions, rate limits, or error handling, which are common gaps for mutation tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core action and resource. Each sentence adds value: the first explains the pruning logic, the second covers VACUUM and automation, and the third provides usage guidance. There is no redundant or wasted information, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a mutation tool with no annotations and no output schema, the description is fairly complete. It covers the tool's purpose, behavioral traits, and usage guidelines. However, it lacks details on output format or error responses, which would be helpful for an agent invoking the tool, slightly reducing completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds minimal semantic context beyond the schema, such as implying the purpose of parameters in the retention policy (e.g., 'older data' relates to recentDays), but it doesn't provide significant additional meaning or examples. This meets the baseline of 3 when schema coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Apply data retention policy', 'Removes low-value rows') and resource ('synced property database'), distinguishing it from siblings like sync_gsc_data or query_gsc_data by focusing on cleanup rather than data retrieval or synchronization. It explicitly mentions the tool's unique function of pruning based on criteria like zero clicks and low impressions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool vs. alternatives: it states 'Use preview_prune first to see what would be deleted,' indicating a clear alternative for previewing deletions. It also notes 'This runs automatically after each sync, but you can also trigger it manually,' clarifying the context for manual invocation versus automated execution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a read-only SQL query against a synced GSC property database. Supports any SELECT query. INSERT/UPDATE/DELETE/DROP/ALTER/CREATE are blocked. The table is "search_analytics" with columns: date, query, page, device, country, clicks, impressions, ctr, position. Requires synced data — run setup first if needed.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | GSC property URL. | |
| sql | Yes | SQL SELECT query to run against the search_analytics table. | |
| params | No | Optional parameterised query values. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: read-only nature, supported/blocked SQL operations, table schema with columns, and prerequisite data sync requirement. It doesn't mention rate limits, error handling, or result format, keeping it from a perfect score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with zero waste: first states purpose and constraints, second details table structure, third provides prerequisite. Each sentence adds essential information, and the description is appropriately front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a query tool with no annotations and no output schema, the description does well by covering purpose, constraints, table schema, and prerequisites. It lacks details on return format, pagination, or error cases, but given the context signals, it's reasonably complete for agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing a solid baseline. The description adds context about the 'sql' parameter ('Supports any SELECT query') and implies 'siteUrl' relates to GSC property, but doesn't elaborate on 'params' usage. It meets the baseline for high schema coverage without significant added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('run a read-only SQL query') and resources ('against a synced GSC property database'). It distinguishes from siblings by specifying it's for querying the search_analytics table, unlike setup, sync, or dashboard tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('run a read-only SQL query... Supports any SELECT query') and when not to use ('INSERT/UPDATE/DELETE/DROP/ALTER/CREATE are blocked'). Provides a prerequisite ('Requires synced data — run setup first if needed') and distinguishes from siblings by specifying the table structure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
First time? Start here. Connects to Google Search Console, syncs all your properties (fetches up to 3 months of data), and shows a visual overview of every site. Takes a few minutes depending on how many properties you have. After setup, use get_overview to see all sites at a glance, or get_dashboard to drill into one.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the tool connects to an external service (Google Search Console), performs data syncing (fetches up to 3 months of data), provides visual output (shows a visual overview), and has variable execution time (takes a few minutes depending on property count). It doesn't mention error handling or authentication requirements, but covers the core behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly structured and concise. It starts with the primary use case, explains what the tool does, provides timing context, and concludes with clear next steps. Every sentence adds value with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter setup tool with no annotations or output schema, the description provides excellent context about what the tool does, when to use it, and what happens during execution. It could potentially mention authentication requirements or error scenarios, but given the tool's nature as a one-time setup, the description is quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't waste space discussing non-existent parameters and instead focuses on the tool's purpose and behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Connects to Google Search Console, syncs all your properties, shows a visual overview') and distinguishes it from siblings by explicitly naming alternatives ('use get_overview to see all sites at a glance, or get_dashboard to drill into one'). It goes beyond just restating the name/title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool ('First time? Start here') and when to use alternatives ('After setup, use get_overview... or get_dashboard...'). It clearly differentiates this initial setup tool from ongoing usage tools like get_overview and get_dashboard.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sync search analytics data for ALL accessible GSC properties in one call. Syncs up to 2 properties in parallel for faster completion. Returns immediately with a job ID — use check_sync_status to monitor progress.
| Name | Required | Description | Default |
|---|---|---|---|
| startDate | No | Start date (YYYY-MM-DD). Defaults to 3 months ago (or incremental from last sync). | |
| endDate | No | End date (YYYY-MM-DD). Defaults to today. | |
| dimensions | No | Dimensions to fetch. Defaults to ["query","page","date","device","country"]. | |
| searchType | No | Search type filter. Default: web. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it's an asynchronous operation (returns immediately with a job ID), handles up to 2 properties in parallel for performance, and requires follow-up with 'check_sync_status'. However, it doesn't mention potential rate limits, authentication requirements, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with three sentences that each earn their place: first states purpose and scope, second explains performance characteristics, third describes return behavior and monitoring. It's front-loaded with the core functionality and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (asynchronous batch operation), no annotations, and no output schema, the description does well by explaining the asynchronous nature, parallel processing, and monitoring requirement. However, it doesn't describe what data gets synced beyond 'search analytics data' or potential limitations (e.g., property count caps, data freshness).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing detailed documentation for all 4 parameters. The description adds no additional parameter information beyond what's in the schema, so it meets the baseline of 3 where the schema does the heavy lifting. No compensation is needed given the high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Sync search analytics data'), the resource ('ALL accessible GSC properties'), and the scope ('in one call'), distinguishing it from sibling tools like 'sync_gsc_data' which likely handles individual properties. The verb 'Sync' is precise and the resource scope is explicitly defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('for ALL accessible GSC properties in one call') and provides a clear alternative for monitoring progress ('use check_sync_status to monitor progress'), distinguishing it from siblings like 'sync_gsc_data' (implied for single properties) and 'cancel_sync' (for stopping operations).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch Google Search Console search analytics data into a local SQLite database. Supports full pagination to capture ALL rows (no 1,000-row limit). Default date range is 3 months. Pass explicit startDate for longer ranges (up to 16 months). Returns immediately with a job ID — use check_sync_status to monitor progress.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | GSC property URL, e.g. "sc-domain:example.com" or "https://www.example.com/" | |
| startDate | No | Start date (YYYY-MM-DD). Defaults to 3 months ago. | |
| endDate | No | End date (YYYY-MM-DD). Defaults to today. | |
| dimensions | No | Dimensions to fetch. Defaults to ["query","page","date","device","country"]. | |
| searchType | No | Search type filter. Default: web. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the asynchronous nature (returns immediately with job ID), the need to monitor progress via another tool, the pagination capability to overcome API limits, default date ranges, and maximum range constraints. It doesn't mention authentication requirements, rate limits, or error handling, but covers most essential operational aspects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly front-loaded with the core purpose in the first sentence, followed by important behavioral details. Every sentence adds value: pagination capability, date range defaults and limits, and asynchronous execution pattern. There's zero wasted text or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no annotations, and no output schema, the description provides substantial context about behavior, defaults, constraints, and the asynchronous workflow. It doesn't explain the return format (though it mentions job ID) or error conditions, but given the schema's excellent coverage and the clear behavioral description, it's mostly complete for agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds some context about default date ranges (3 months, up to 16 months with explicit startDate) and the pagination benefit, but doesn't provide additional semantic meaning beyond what's in the schema descriptions. This meets the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Fetch Google Search Console search analytics data into a local SQLite database'), identifies the resource (GSC data), and distinguishes it from siblings by mentioning its unique pagination capability and asynchronous job-based execution. It goes beyond just restating the name/title.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when to use this tool (for fetching GSC data with full pagination, default 3-month range, up to 16 months with explicit startDate) and explicitly mentions an alternative tool for monitoring progress (check_sync_status). However, it doesn't explicitly state when NOT to use it or compare it to other siblings like query_gsc_data or sync_all_properties.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.4cancel_synccheck_sync_statuscompare_periodsget_dashboardget_insightsget_overviewlist_propertiesprune_databasequery_gsc_datasetupsync_all_propertiessync_gsc_dataScored across 12 tools
Most tools have distinct purposes, such as setup for initial configuration, sync_gsc_data for data fetching, and get_insights for analysis. However, there is some overlap between sync_gsc_data and sync_all_properties, as both handle data syncing but differ in scope (single vs. all properties), which could cause minor confusion for agents. Overall, descriptions help clarify differences, but the redundancy in syncing tools slightly reduces clarity.
Tool names consistently follow a verb_noun pattern, such as cancel_sync, check_sync_status, compare_periods, and get_dashboard. All tools use snake_case without deviations, making the naming predictable and easy to parse. This uniformity enhances agent usability and reduces cognitive load when selecting tools.
With 12 tools, the server is well-scoped for managing Google Search Console data, covering setup, syncing, monitoring, analysis, and maintenance. Each tool serves a specific function, such as data retrieval (sync_gsc_data), insights (get_insights), and cleanup (prune_database), ensuring comprehensive coverage without bloat. The count aligns well with the domain's complexity.
The tool set provides complete coverage for the Google Search Console domain, including initial setup (setup), data syncing (sync_gsc_data, sync_all_properties), monitoring (check_sync_status, cancel_sync), analysis (get_insights, compare_periods, query_gsc_data), visualization (get_overview, get_dashboard), and maintenance (prune_database, list_properties). There are no obvious gaps, supporting full CRUD-like workflows from data ingestion to insights.
Query your SEO data in plain language: rankings, audits, backlinks, competitors and AI visibility.
Turn Search Console data into SEO actions, content, publishing, indexing, and AI insights.
Query your Google Search Console, GA4 and Bing Webmaster data across every site you run.
Ask Google Search Console in plain language. Hosted, free, no Google Cloud project.
