Provides direct access to Google Search Console data, allowing AI agents to query search analytics (clicks, impressions, CTR, and average position), check URL indexing status, and monitor sitemap status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Google Search Console MCP Server show my top search queries for example.com from the last 30 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A minimal MCP server for Google Search Console.
Give Codex, Claude Code, or Claude Desktop read-only access to your search analytics, URL indexing information, and sitemap status. Runs locally; cannot change your site or Search Console settings.
Once connected, ask your agent:
"Which queries had the most impressions but few clicks over the last 28 days?"
"Compare mobile vs desktop search performance this month."
"Check the indexing status of https://example.com/blog/my-post."
Setup · Tools · Limitations · Troubleshooting
You need Node.js and npm, an MCP client, and access to a Search Console property. To sign in as yourself, also install the Google Cloud CLI. Server startup and tool discovery were checked with Node.js 22.
Create or select a project in Google Cloud Console, then enable the Search Console API. Note the project ID for the next step.
Recommended for new users: sign in as yourself. Application Default Credentials (ADC) use your existing Search Console permissions, so you don't need to add another user to your properties.
Run both commands, replacing YOUR_PROJECT_ID with the project you enabled above:
gcloud auth application-default login \
--scopes=https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform
gcloud auth application-default set-quota-project YOUR_PROJECT_IDThe quota project is required. For permission or scope errors, see troubleshooting.
In Google Cloud Console, go to APIs & Services → Credentials → Create Credentials → Service account. Name it and finish creation; you can skip the optional role/access steps.
Open the service account, then Keys → Add Key → Create new key → JSON to download a key.
In Search Console, open each property's Settings → Users and permissions → Add user. Add the service account email with Restricted access.
Store the key outside your repo and never commit it. Use its absolute path in your client's configuration below.
If Search Console rejects the email with "Failed to add user: email not found," sign in as yourself instead; see troubleshooting.
The server checks GOOGLE_APPLICATION_CREDENTIALS before local ADC. If switching to ADC, remove an old key-path setting from your client configuration and environment.
The npx commands in the next step download and run version 1.1.0 for you. Both authentication methods work with the npm package; no clone or build is required.
git clone https://github.com/sarahpark/google-search-console-mcp.git
cd google-search-console-mcp
npm install
npm run buildIn the client commands below, replace npx -y @sarahpark/google-search-console-mcp@1.1.0 with node "/absolute/path/to/google-search-console-mcp/build/index.js". In Claude Desktop, set command to node and args to an array containing that absolute path. Run npm test for offline authentication checks.
After completing authentication, paste this into your agent:
Add
npx -y @sarahpark/google-search-console-mcp@1.1.0asgscin this client's user-level MCP config, preserving existing servers. Use my local Application Default Credentials. Tell me when setup is complete and whether I need to restart the client.
For a service account, replace "Use my local Application Default Credentials" with "Set GOOGLE_APPLICATION_CREDENTIALS to /path/to/service-account-key.json" and use your actual file location.
Once configured, skip to step 5.
Choose your client and run the command for your authentication method. Replace placeholder paths with your actual absolute paths; keep quotes around paths containing spaces. Preserve any existing server entries.
Sign in as yourself (ADC):
codex mcp add gsc -- npx -y @sarahpark/google-search-console-mcp@1.1.0npm package with a service account:
codex mcp add gsc \
--env "GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account-key.json" \
-- npx -y @sarahpark/google-search-console-mcp@1.1.0For manual configuration in ~/.codex/config.toml, see the Codex MCP documentation.
Sign in as yourself (ADC):
claude mcp add gsc --scope user -- npx -y @sarahpark/google-search-console-mcp@1.1.0npm package with a service account:
claude mcp add gsc --scope user \
--env "GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/service-account-key.json" \
-- npx -y @sarahpark/google-search-console-mcp@1.1.0--scope user makes the server available across your projects. Use --scope project to share configuration through the project's .mcp.json instead.
Add the appropriate entry to claude_desktop_config.json, merging it into any existing mcpServers object.
Sign in as yourself (ADC):
{
"mcpServers": {
"gsc": {
"command": "npx",
"args": ["-y", "@sarahpark/google-search-console-mcp@1.1.0"]
}
}
}npm package with a service account:
{
"mcpServers": {
"gsc": {
"command": "npx",
"args": ["-y", "@sarahpark/google-search-console-mcp@1.1.0"],
"env": {
"GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
}
}
}
}Restart your client or start a new session, then ask:
Use the gsc MCP server to list my Search Console properties.
A successful list_sites call verifies both the connection and Google access. Use the exact property URL it returns in later requests, such as sc-domain:example.com or https://example.com/.
Related MCP server: Google Search Console MCP Server
List all sites (properties) you have access to in Google Search Console.
No parameters required.
Query search analytics data — clicks, impressions, CTR, and position.
Parameter | Type | Required | Description |
| string | Yes | Site URL as it appears in Search Console (e.g. |
| string | Yes | Start date in |
| string | Yes | End date in |
| string | No | Comma-separated: |
| number | No | Max rows to return (default 100, max 25000) |
| string | No |
|
| string | No | Filter by query. Prefix with |
| string | No | Filter by page URL. Prefix with |
| string | No | ISO 3166-1 alpha-3 country code (e.g. |
| string | No |
|
Check indexing status, crawl info, and mobile usability for a URL.
Parameter | Type | Required | Description |
| string | Yes | Site URL as it appears in Search Console |
| string | Yes | The full URL to inspect (must belong to the site) |
List all submitted sitemaps and their status for a site.
Parameter | Type | Required | Description |
| string | Yes | Site URL as it appears in Search Console |
Search analytics returns at most 25,000 rows per call, without pagination. Results may omit pages or queries, and recent data may be incomplete.
URL inspection checks one URL at a time; it does not export a site's full indexing coverage report.
Your agent performs comparisons and opportunity analysis using the returned data. This is a local STDIO server, not a hosted ChatGPT web integration.
If the error says the API "requires a quota project," rerun:
gcloud auth application-default set-quota-project YOUR_PROJECT_IDYour account needs serviceusage.services.use on that project. If permission is denied, ask a project administrator to grant it or use a project where you have it, with the Search Console API enabled.
Login attempts to attach your configured project automatically but can skip it when you lack permission. Setting it explicitly makes that failure visible. The cloud-platform scope in the setup command allows the quota project to be attached.
The built-in gcloud client was confirmed to grant webmasters.readonly with Google Cloud SDK 557.0.0. If it doesn't work in your version, follow the gcloud guidance for additional scopes to create your own OAuth client, then sign in with its downloaded client file:
gcloud auth application-default login \
--client-id-file=client_id.json \
--scopes=https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/cloud-platform
gcloud auth application-default set-quota-project YOUR_PROJECT_IDKeep credential files outside your repo.
This has been reported when adding newly created service accounts and motivated the ADC option. Sign in as yourself, or use an existing service account that already has access to the property.
Using npm 1.0.1 or earlier: update your client command to version 1.1.0 or later to use local gcloud ADC.
Using ADC: ensure an old GOOGLE_APPLICATION_CREDENTIALS setting isn't overriding your login. The signed-in Google account must have access to the property.
Using a service account: set GOOGLE_APPLICATION_CREDENTIALS to the key's absolute path and confirm its email was added to each property you want to read.
Inspect a URL to check its indexing status, crawl info, and any issues Google found.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Site URL as it appears in Search Console | |
| inspectionUrl | Yes | The full URL to inspect (must belong to the site) |
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. The description implies a read-only operation (inspecting a URL) but never explicitly states that it is non-destructive, does not modify state, or has any rate limits or access requirements. It also omits what 'issues Google found' means in practice.
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 sentence with no filler. It is front-loaded with the action ('Inspect a URL') and immediately conveys the core purpose. Every word 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?
For a simple two-parameter read tool, the description is adequate but not complete. It does not disclose the output format (no output schema provided), nor does it mention any auth or verification requirements. Given no annotations, the description should have noted that this is a read-only operation and what kind of data it returns. It covers the main purpose but leaves operational details to inference.
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%, with both parameters (siteUrl and inspectionUrl) having clear descriptions. The tool description does not add any additional meaning beyond the schema; it merely summarizes the tool's purpose. Since the schema already documents the parameters, the 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 states a specific verb ('Inspect') and a specific resource ('a URL') and lists three concrete outcomes: indexing status, crawl info, and issues Google found. This clearly distinguishes it from sibling tools (list_sites lists sites, search_analytics reports analytics, list_sitemaps lists sitemaps).
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 no guidance on when to use this tool vs. alternatives. It does not mention prerequisites (e.g., site verification in Search Console), nor does it contrast with search_analytics or list_sitemaps. An agent cannot infer the appropriate context from this description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all sitemaps submitted for a site in Google Search Console.
| Name | Required | Description | Default |
|---|---|---|---|
| siteUrl | Yes | Site URL as it appears in Search Console |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. 'List all' strongly implies a read-only operation, but it does not explicitly state that nothing is modified, whether any special authorization is required, or how invalid siteUrl values are handled. These are useful details an agent would need to invoke confidently.
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 clear sentence with no filler, front-loading the action and resource. It is appropriately concise for a simple one-parameter tool, though it is terse enough to omit helpful context that would make it more informative.
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—one required parameter and no nested objects or output schema—the description gives enough context for an agent to understand the operation and provide the correct siteUrl. It could add details about what a returned sitemap list contains or the format of siteUrl, but these are minor gaps, not blockers.
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%, and the sole parameter siteUrl is described as 'Site URL as it appears in Search Console.' The tool description adds no extra semantic detail beyond this, so it meets the baseline but does not enhance parameter 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 names a clear verb and resource: 'List all sitemaps submitted for a site in Google Search Console.' This distinguishes it from siblings like list_sites, search_analytics, and inspect_url, which cover different resources or actions.
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 when to use it: when you need sitemaps associated with a Search Console site. However, it gives no explicit guidance about when not to use it or what alternatives like search_analytics or inspect_url are better for, leaving route selection mostly to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all sites (properties) you have access to in Google Search Console.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the disclosure burden. It accurately indicates a read-only list operation and scopes results to accessible sites. However, it does not disclose pagination, return format, or potential permission nuances beyond the access scope, leaving some behavioral expectations unstated.
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 with no redundant words. It names the action, resource, and scope with maximum brevity, and every element 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?
For a zero-param, zero-schema tool, the description adequately conveys the operation and scope. It lacks an explicit return structure, but the simple list nature makes this acceptable; the description is complete enough for an agent to invoke the tool correctly.
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 schema imposes no burden. The description adds a meaningful qualifier ('you have access to') that shapes the result set, aligning with the baseline 4 for parameter-free 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 clearly states a specific action ('List all sites'), the resource ('sites (properties)'), and the scope ('you have access to'). This distinguishes it from siblings like search_analytics and inspect_url, which are query/action tools. An agent can immediately understand the tool's purpose and differentiate it from alternatives.
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 by defining the result set as sites the caller has access to, but it does not explicitly mention when to use this tool versus siblings or any prerequisites. No exclusions or alternative tool names are provided, leaving the agent to infer context from the sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query search analytics data from Google Search Console. Returns clicks, impressions, CTR, and position for your site.
| Name | Required | Description | Default |
|---|---|---|---|
| endDate | Yes | End date in YYYY-MM-DD format | |
| siteUrl | Yes | Site URL exactly as it appears in Search Console (e.g. https://example.com/ or sc-domain:example.com) | |
| rowLimit | No | Max rows to return (default 100, max 25000) | |
| startDate | Yes | Start date in YYYY-MM-DD format | |
| dimensions | No | Comma-separated dimensions: query, page, country, device, searchAppearance, date | |
| pageFilter | No | Filter by page URL. Prefix with regex: for regex matching. | |
| searchType | No | Type of search results to query | web |
| queryFilter | No | Filter by search query. Prefix with regex: for regex matching. | |
| deviceFilter | No | Filter by device type | |
| countryFilter | No | Filter by country (ISO 3166-1 alpha-3, e.g. USA, GBR) |
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, but it only says the tool 'queries' and returns four metrics. It does not mention limits, pagination, data freshness, permissions, or the lack of side effects, leaving agents without safety or constraint awareness.
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 short sentences, no filler, and the core query-plus-output information is front-loaded. The definition is well-sized for a tool whose parameter details live in the schema.
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 100% schema coverage, the description plus schema is minimally viable: it names the data source, the output metrics, and all parameters are documented. However, with no output schema and no annotations, the absence of usage guidance, filter behavior, and limits leaves clear gaps.
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 fully documents all ten parameters. The description adds no parameter-specific meaning and instead focuses on return metrics; the baseline of 3 is appropriate since the structured schema handles parameter semantics.
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 identifies a specific verb-resource pair ('Query search analytics data') and states the returned metrics, making it clear this is a read-only analytics retrieval tool. It does not explicitly differentiate from sibling tools such as list_sites or inspect_url, though the distinct resource domain is apparent.
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?
There is no guidance about when to choose this tool over the sibling tools, and no mention of prerequisites or exclusions. The usage context is only implied by the tool name and the mention of Google Search Console metrics.
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.1.0inspect_urllist_sitemapslist_sitessearch_analyticsScored across 4 tools
Each tool targets a distinct Google Search Console resource and action: site listing, analytics queries, URL inspection, and sitemap listing. There is no overlap in purpose, so an agent can easily select the right tool for a given task.
All tools follow a consistent verb_noun pattern in lowercase snake_case (list_sites, search_analytics, inspect_url, list_sitemaps). The naming is predictable and uniform across the entire set.
Four tools is a reasonable size for a focused read-only Search Console server. It is slightly lean but each tool covers a distinct core function, and the count feels appropriate for the apparent scope.
The server covers primary read operations but misses common management actions like submitting or deleting sitemaps. Analytics and URL inspection are present, but there is no sitemap submission or deeper detail (e.g., sitemap errors), leaving notable gaps for workflows.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Google Search Console in your AI: overview, opportunities, index gaps, page checks, long history.
SEO data your AI can cite: Search Console, GA4, keywords, backlinks, SERPs and AI visibility.
SEO answers for AI agents: Search Console reads free, plus competitor, keyword, backlink, SERP data.
