search-console-mcp
Provides tools for interacting with Google Search Console, enabling analysis of search performance data, URL inspection, sitemap listing, and period-over-period comparisons, with built-in SEO analyses such as cannibalization detection and striking distance opportunities.
search-console-mcp
Search Console was built for dashboards. This gives you a conversation instead.
Talk to your Google Search Console from Claude, Cursor, or any MCP client.
One sign-in. 30 seconds. No Google Cloud project. No API keys. Tokens never leave your machine.
Docs · npm · Report an issue
Google Search Console
│
▼
search-console-mcp ← runs on your machine, read-only
│
▼
Claude / Cursor / any MCP client
│
▼
"Why did my traffic drop?"Every other Search Console MCP server makes you create a Google Cloud project, enable APIs, and wrangle service-account JSON. This one doesn't:
npx search-console-mcp-server loginYour browser opens, you sign in with Google, done. Tokens are minted by Google directly to your machine and stored only in ~/.search-console-mcp/ — nothing passes through anyone's servers.
This server | Typical GSC MCP setup | |
Setup |
| Create a Google Cloud project, enable the API, create OAuth credentials, download JSON, point config at it |
Runtime | Node — | Python + uv/venv |
Can it modify your site data? | Impossible — read-only scope by construction | Write scopes with destructive ops "disabled by default" |
Analyses | 5 built-in (checkup, cannibalization, striking distance, traffic drop, indexing audit) | Bring your own prompts |
What to expect on first run
$ npx search-console-mcp-server login
Opening your browser to sign in with Google…
Connected. Your Search Console is ready — tokens stored in
~/.search-console-mcp (this machine only).That's the whole setup. No clone, no Google Cloud console, no JSON files.
Related MCP server: GSC SEO MCP
What it feels like
You: Which of my pages are closest to page one?
Claude: Three real opportunities, by impressions at stake:
1. /pricing — "scoreboard app pricing" sits at position 11.2 with
2,400 impressions/mo and almost no clicks. One position-group
jump is worth ~90 clicks/mo. The title doesn't contain the
query; start there.
2. /templates/trivia — position 12.8 on "trivia scoreboard",
1,100 impressions/mo. The page ranks but has no H2 matching
the intent.
3. /blog/keep-score-online — position 9.4, already page one on
some days. It's cannibalizing with /features — run
cannibalization_check before touching it.(Illustrative output — shape and numbers are what the tools return from your real data.)
Built-in SEO analysts
Five ready-made analyses ship as MCP prompts — slash-commands in clients that support them. Outcomes, not API calls:
Prompt | What you get |
| Trend vs last month, biggest movers, and the top 3 moves worth making |
| Queries where two of your pages compete — which should win, and how to fix it |
| Queries sitting at position 5–15 — the fastest traffic you're not getting, with the fix per page |
| When the drop started, which pages/queries lost, indexed-or-not, most likely cause |
| Sitemap status + index inspection of your top pages, with plain-language fixes |
Setup
1. Sign in (one time):
npx search-console-mcp-server login2. Add to your MCP client:
Claude Code:
claude mcp add gsc -- npx -y search-console-mcp-serverClaude Desktop / Cursor / anything else (mcpServers config):
{
"mcpServers": {
"gsc": { "command": "npx", "args": ["-y", "search-console-mcp-server"] }
}
}3. Ask:
"Which of my pages lost the most clicks this month vs last?"
"Show my queries sitting at position 8–15 with real impressions — what's closest to page 1?"
"Is https://mysite.com/pricing indexed? If not, why?"
"How much Google Discover traffic do I get?"
Tools
Tool | What it does |
| Your GSC properties (call first — gives exact |
| Clicks / impressions / CTR / position by query, page, date, country, device — filters, pagination, and every traffic source including Google Discover |
| Biggest movers, computed for you: this period vs the prior one, per-page or per-query deltas, sorted by change |
| Google's index status for a URL: indexed or not, why, chosen canonical, last crawl |
| The same, batched — up to 10 URLs in one call for indexing audits |
| Submitted sitemaps with status |
Read-only by construction: the Google scope this tool requests (webmasters.readonly) cannot modify your properties, submit sitemaps, or change anything — not "disabled by default." Impossible.
What a compare_periods call hands your model (the model never does date arithmetic):
{ "key": "https://example.com/pricing",
"current": { "clicks": 1040, "impressions": 20502, "position": 6.4 },
"previous": { "clicks": 1070, "impressions": 17176, "position": 5.8 },
"deltaClicks": -30, "deltaImpressions": 3326, "deltaPosition": 0.6 }Privacy
Read-only Google scope (
webmasters.readonly).Tokens live in
~/.search-console-mcp/credentials.jsonon your machine,chmod 600.npx search-console-mcp-server logoutdeletes them.No telemetry, no proxy — API calls go from your machine to Google, full stop.
Prefer your own Google Cloud project? Set
SEARCH_CONSOLE_MCP_CLIENT_ID/SEARCH_CONSOLE_MCP_CLIENT_SECRETand it uses yours.
FAQ / Troubleshooting
How can the login work without me creating Google credentials?
The CLI ships a Google "Desktop app" OAuth client — the same supported model gcloud and GitHub's CLI use. Your tokens are still minted by Google directly to your machine (PKCE + localhost callback); they never touch our servers. The entire auth path is ~200 lines in src/auth.ts — read it. Want zero shared anything? Set SEARCH_CONSOLE_MCP_CLIENT_ID / SEARCH_CONSOLE_MCP_CLIENT_SECRET with your own credentials.
Switch Google accounts?
npx search-console-mcp-server login again — Google shows the account picker.
"Not signed in" errors in my MCP client?
Run the login from the same user account your client runs under; credentials live in ~/.search-console-mcp/.
A property is missing from list_properties.
The signed-in Google account needs at least "Restricted" access to it in Search Console.
Why is yesterday missing from the data? Google Search Console data lags ~2–3 days. That's Google, not the tool. History goes back ~16 months.
Revoke access?
npx search-console-mcp-server logout deletes local tokens; myaccount.google.com/permissions revokes the grant itself.
Development
git clone https://github.com/sudomichael/search-console-mcp
cd search-console-mcp && npm install
npm run dev # run from source
npm run build # bundle to dist/ (10KB, no googleapis dependency)The entire auth path is ~200 lines in src/auth.ts. To verify any privacy claim above, read the source.
Looking for something proactive?
This MCP server helps you investigate — you ask, it answers.
After a week you may notice you keep asking the same questions: What dropped? What's closest to page one? What should I fix?
Percy is the other half: he checks your Search Console every week on his own, builds a strategy, emails you exactly what to change — then re-checks the live page and measures whether it worked.
Exploration here. Execution there. Same philosophy: real data, plain English, no dashboards.
MIT licensed. Issues and PRs welcome. Built by Percy.
Available Tools
6 toolscompare_periodsA
The biggest-movers analysis, computed for you: this date range vs the prior equal-length range, joined per page (or query) with clicks/impressions/position deltas, sorted by biggest change. Use this for 'what fell/grew', 'this month vs last', and trend diagnosis — it's one call and the math is already done.
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | Yes | Current period end, YYYY-MM-DD | |
| siteUrl | Yes | Exact property from list_properties | |
| rowLimit | No | ||
| dimension | No | Compare by page (default) or by query | |
| startDate | Yes | Current period start, YYYY-MM-DD | |
| searchType | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It discloses output structure (clicks/impressions/position deltas sorted by biggest change) and that it's a read-only computation ('math is already done'). Does not mention rate limits or permissions, but is generally transparent.
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, front-loaded with the core action, zero wasted words. Every sentence adds value.
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 no output schema, the description explains the computed output (deltas, sorted) and use cases. Could mention that it returns a list of items and that prior period is automatically calculated, but overall adequate.
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 67%, and description adds value by explaining date range comparison and dimension (page/query). However, it does not elaborate on rowLimit, searchType, or siteUrl beyond the schema, missing opportunity to clarify constraints.
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 it's a 'biggest-movers analysis' comparing two periods with deltas, sorted by biggest change. It distinguishes from siblings like query_search_analytics by offering pre-computed period comparison, not raw data.
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 says 'Use this for 'what fell/grew', 'this month vs last', and trend diagnosis' – providing clear when-to-use guidance. Lacks explicit when-not-to or alternative tools, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
inspect_urlA
Google's index status for one URL: is it indexed, why not, canonical chosen by Google, last crawl, mobile/rich-result issues.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Exact property from list_properties | |
| inspectionUrl | Yes | Full URL to inspect |
TDQS
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 what the tool returns (index status, canonical, etc.) but omits behavioral traits such as read-only nature, authentication, rate limits, or any side effects.
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 a single, front-loaded sentence that efficiently lists key outputs with no unnecessary 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 simple two-parameter inspection tool with full schema coverage and no output schema, the description covers the return information reasonably well. It lacks error handling or edge case details but is sufficient for basic understanding.
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 coverage is 100% with clear descriptions for both parameters. The tool description does not add additional meaning beyond the schema, so baseline of 3 is appropriate.
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: providing Google's index status for a single URL, listing specific data points like index status, canonical URL, last crawl, and mobile/rich-result issues. It distinguishes from the sibling tool 'inspect_urls' which implies multiple URL inspection.
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 does not explicitly state when to use this tool versus alternatives like 'inspect_urls' for multiple URLs. It implies single-URL inspection but lacks direct guidance on prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
inspect_urlsA
Batch index-status check: up to 10 URLs in one call (per-URL errors reported inline). Use for indexing audits instead of ten single calls.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Exact property from list_properties | |
| inspectionUrls | Yes | Full URLs to inspect (max 10) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses batch limit (up to 10) and per-URL error reporting. Does not explicitly state read-only nature or authorization needs, but the description is adequate for a simple batch check.
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 compact sentences that convey purpose, batch limit, error handling, and usage recommendation. No 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?
Covers main functional aspects: batch, error reporting, and usage advice. Lacks output format description, but given simplicity and sibling context, it is reasonably 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?
Schema coverage is 100% with good descriptions for both parameters. Description adds value by indicating 'siteUrl' must come from list_properties and 'inspectionUrls' are full URLs, plus the batch context.
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 'Batch index-status check' and specifies the action of inspecting up to 10 URLs in one call. It distinguishes from the sibling 'inspect_url' by emphasizing batching and efficiency.
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 suggests using this tool 'for indexing audits instead of ten single calls,' providing clear context on when to prefer it. Could mention when not to use it, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_propertiesA
List the Google Search Console properties this account can access. Call this first to get exact siteUrl values (e.g. 'sc-domain:example.com' or 'https://example.com/').
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It describes the read-only list operation adequately but does not detail response format or potential constraints like rate limits.
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 concise sentences front-load the core action and add practical guidance. Every sentence adds value with no 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 simple list tool with no output schema, the description covers the use case and return value context. Minor improvement could explicitly state the return format, but it's sufficient.
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 zero parameters, so the description need not add parameter info. Baseline score of 4 applies as per rules for 0-parameter tools.
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 uses a specific verb 'List' and resource 'Google Search Console properties', clearly distinguishing it from sibling tools like query_search_analytics or list_sitemaps. The example siteUrl values further clarify the purpose.
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 'Call this first to get exact siteUrl values', providing clear guidance on when to use this tool. It does not exclude other uses but sets a priority context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_sitemapsA
List submitted sitemaps for a property, with status and counts.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Exact property from list_properties |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It indicates a read operation (listing), which is standard, but does not mention permissions, rate limits, or any side effects. For a simple list tool, this is minimally adequate.
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 a single, well-structured sentence with no unnecessary words. It efficiently conveys the tool's purpose and outputs.
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 no output schema and no annotations, the description lacks details on return format, pagination, or what 'status and counts' entail. For a tool with minimal complexity, this may suffice, but it leaves gaps for optimal 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% for the single parameter. The description adds no extra meaning beyond the schema's 'Exact property from list_properties', so it meets the baseline but does not enhance understanding.
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 lists submitted sitemaps for a property, including status and counts. It distinguishes itself from sibling tools (e.g., inspect_url, list_properties) by focusing specifically on sitemap listing.
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 does not provide guidance on when to use this tool over alternatives or indicate any prerequisites (e.g., need to call list_properties first). The parameter hint 'Exact property from list_properties' implicitly suggests a dependency, but explicit usage conditions are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
query_search_analyticsA
Query real Search Console performance data: clicks, impressions, CTR, and average position, grouped by the dimensions you choose. Dates are YYYY-MM-DD (GSC data lags ~2-3 days). Use dimensions like ['query'], ['page'], ['query','page'], or ['date'] for trends.
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | Yes | YYYY-MM-DD | |
| siteUrl | Yes | Exact property from list_properties | |
| rowLimit | No | ||
| startRow | No | Pagination offset — pass 1000, 2000, … for more rows | |
| startDate | Yes | YYYY-MM-DD | |
| dimensions | No | Grouping, default ['query'] | |
| searchType | No | Traffic source — 'discover' shows Google Discover performance | |
| pageContains | No | Only page URLs containing this | |
| queryContains | No | Only queries containing this |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses data lag (~2-3 days) and date format. However, it does not mention pagination behavior, rate limits, or authentication requirements. The transparency is adequate but not thorough.
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 two sentences with no wasted words. The first sentence defines purpose and output, the second adds critical usage details (date format, lag, dimension examples). Every sentence earns its place.
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 no output schema and no annotations, the description covers key aspects (metrics, grouping, date lag) but omits pagination (startRow, rowLimit), filtering (searchType, queryContains), and behavior details. It is adequate but not fully complete for a complex tool with 9 parameters.
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 89%, so most parameters are documented. The description adds value by providing example dimension arrays and noting date format and data lag, which complements the schema. This extra context justifies a score above baseline.
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 queries real Search Console performance data and lists metrics (clicks, impressions, CTR, average position) grouped by chosen dimensions. It distinguishes from sibling tools like inspect_url or list_properties by focusing on analytics data.
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 context for use (querying performance data) and gives dimension examples, but lacks explicit guidance on when to use this tool versus alternatives or exclusions. It implies usage but no when-not-to or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Each tool targets a distinct aspect of Google Search Console: trend analysis, URL index checks (single and batch), property listing, sitemap listing, and performance data querying. There is no overlap in functionality.
All tool names follow a consistent verb_noun pattern with snake_case (e.g., inspect_url, list_properties, query_search_analytics). No mixing of conventions.
With 6 tools, the server is well-scoped for common Search Console tasks. The count is neither too small nor too large for the domain.
The set covers essential CRUD-like operations (list properties, list sitemaps, inspect URLs, query data, compare periods). Minor gaps exist, such as lacking tools for sitemap submission or crawl rate management, but the core workflows are supported.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Read and edit GA4, Search Console and Google Tag Manager from any MCP client. 29 tools.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Live SEO workflow tools for Claude Code, Codex, and AI agents.
Run SEO + AI-visibility (GEO) audits from Claude, Cursor & other AI clients.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceSelf-hosted MCP server that exposes Google Search Console tools (list sites, query analytics, inspect URL, list sitemaps) via natural language to AI assistants like ChatGPT and Claude.1MIT
- AlicenseBqualityBmaintenanceProfessional Google Search Console MCP server providing 40+ SEO tools for performance analysis, content decay, CTR opportunities, and more, enabling real search data in clients like Cursor and Claude.40196MIT
- AlicenseNot gradedqualityCmaintenanceSelf-hosted Google Search Console MCP server deployable to Cloudflare Workers, allowing natural language queries of GSC data via ChatGPT, Claude, or any MCP-capable client.MIT
- AlicenseBqualityCmaintenanceA production-oriented, read-only Google Search Console MCP server and TypeScript SDK for Claude, Cursor, VS Code, and other MCP clients. Query real Search Console data, inspect indexed URLs, review sitemaps, compare periods, and surface transparent SEO opportunities without handing private data to a third-party SaaS.20MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sudomichael/search-console-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server