Google Search Console MCP server
A read-only Google Search Console MCP server: query search analytics, compare periods, list sitemaps, and inspect URLs from any MCP client (Claude, Cursor, Claude Code).
list_sites— list properties the service account can see, with permission level.search_analytics— clicks, impressions, CTR and position, broken down by date, query, page, country, device or search appearance; supports ANDed filters (equals, contains, notContains, includingRegex, excludingRegex), pagination (row_limit1–25000,start_row), and search types web/image/video/news/discover/googleNews. Omit dimensions for site-wide totals.compare_periods— two date ranges side by side with deltas, site-wide or per dimension (query, page, country, device); rows present in only one period come back with zeros.list_sitemaps— submitted sitemaps with status, last download, errors/warnings and indexed URL counts.inspect_url— index status, coverage verdict, user vs Google canonical, last crawl, robots/indexing state, mobile and rich-result verdicts (quota 2000 calls/day; needs Owner or Full).Safe by design:
webmasters.readonlyscope only — it cannot change anything in Search Console; auth via rotatable service-account key.Practical notes: data lags ~2 days (default range ends 2 days ago) and Google anonymises long-tail queries, so query totals won't match page totals.
Deployable: stdio via
npxin Claude Code/Desktop/Cursor, a Docker image, or a streamable-HTTP entrypoint (PORT,/healthz) for central/gateway hosting.
Provides read-only access to Google Search Console, including listing properties, querying search analytics by date, query, page, country, device, or search appearance, comparing periods, listing sitemaps, and inspecting URLs.
gsc-mcp — Google Search Console MCP server
A small, read-only Model Context Protocol server that gives Claude, Cursor, Claude Code and any other MCP client access to Google Search Console: search analytics, period comparisons, sitemaps and URL inspection.
Built and used daily by Walma AI to run our own SEO through Claude Code. There is a longer write-up in our guide: Google Search Console MCP.
Why service-account auth: no personal Google login on the machine that runs the agent, a key you can rotate and revoke, and read-only scope. Right for teams and for servers.
Tools
Tool | What it does |
| Properties the service account can see, with permission level |
| Clicks, impressions, CTR and position by date, query, page, country, device or search appearance, with filters and pagination |
| Two date ranges side by side with deltas, site-wide or per dimension |
| Submitted sitemaps with status, errors and indexed counts |
| URL Inspection: index status, canonical, last crawl, mobile and rich-result verdicts |
Everything is read-only (webmasters.readonly scope). The server cannot change anything in Search Console.
Related MCP server: gsc-mcp-connector
Setup
1. Create a service account and key
In Google Cloud Console, pick or create a project.
Enable the Google Search Console API (
searchconsole.googleapis.com).IAM & Admin → Service accounts → Create. No project roles are needed.
Keys → Add key → JSON. Save the file somewhere outside any repository, for example
~/.config/gcloud/gsc-service-account.json.
2. Give the service account access in Search Console
In Search Console, for each property: Settings → Users and permissions → Add user → the service account's e-mail (...@...iam.gserviceaccount.com).
Full is enough for
search_analytics,compare_periodsandlist_sitemaps.inspect_urlneeds Owner or Full depending on the property type.
3. Add it to your client
The server needs Node 20+ and one environment variable: GSC_SERVICE_ACCOUNT_FILE, the path to the JSON key (or GSC_SERVICE_ACCOUNT_JSON with the key inline — useful when the key comes from a secret store rather than disk).
Claude Code
claude mcp add --transport stdio gsc \
-e GSC_SERVICE_ACCOUNT_FILE=~/.config/gcloud/gsc-service-account.json \
-- npx -y @walma-labs/gsc-mcpClaude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"gsc": {
"command": "npx",
"args": ["-y", "@walma-labs/gsc-mcp"],
"env": { "GSC_SERVICE_ACCOUNT_FILE": "/Users/you/.config/gcloud/gsc-service-account.json" }
}
}
}Cursor (.cursor/mcp.json or ~/.cursor/mcp.json)
{
"mcpServers": {
"gsc": {
"command": "npx",
"args": ["-y", "@walma-labs/gsc-mcp"],
"env": { "GSC_SERVICE_ACCOUNT_FILE": "/Users/you/.config/gcloud/gsc-service-account.json" }
}
}
}Use absolute paths in the desktop clients; they do not expand ~ or inherit your shell's PATH.
Running it as a remote server
The package also ships a stateless streamable-HTTP entrypoint for hosting the server centrally (a container, a gateway):
GSC_SERVICE_ACCOUNT_JSON="$(cat key.json)" npx -y -p @walma-labs/gsc-mcp node dist/http.jsIt listens on PORT (default 8080) with a /healthz endpoint, and deliberately has no auth of its own — put your gateway or reverse proxy in front. Programmatic hosts can instead import { createGscServer } from "@walma-labs/gsc-mcp" and mount the returned server on any transport.
Docker
The repository ships a Dockerfile that runs the stdio server as a non-root user:
docker build -t gsc-mcp .
docker run -i --rm -e GSC_SERVICE_ACCOUNT_JSON="$(cat key.json)" gsc-mcpIn an MCP client, use docker as the command with ["run", "-i", "--rm", "-e", "GSC_SERVICE_ACCOUNT_JSON", "gsc-mcp"] as arguments and pass the key through the client's env settings.
Using it
Properties are addressed the way the API addresses them: sc-domain:example.com for domain properties, https://example.com/ for URL-prefix properties. Ask the agent to run list_sites first if unsure.
Things it is good at:
"Which queries drive the most clicks to
/pricing, and what is our average position for each?""Compare the last 28 days with the previous 28. Which pages lost the most clicks, and which queries on those pages dropped?"
"Queries with more than 500 impressions where we rank between 11 and 20."
"Is
/guides/mcpindexed, and what does Google consider the canonical?""List sitemaps and any with errors."
Two things to tell the agent: Search Analytics data lags about two days (the server defaults to a range ending two days ago), and Google anonymises long-tail queries, so totals by query will not match totals by page.
Running it for a team
The key file grants read access to all your search data. On a laptop it is one lost machine away from a leak, and calls are not attributable to a person. For a team, put the server behind a gateway that holds the key centrally, exposes the server to approved users and logs each query. That is how we run it at Walma, behind Walma AI Hub inside our own EU tenant, next to Google Ads, GA4 and Ahrefs.
Development
npm install
npm run build && npm test
GSC_SERVICE_ACCOUNT_FILE=~/.config/gcloud/gsc-service-account.json node dist/stdio.jsThe server speaks MCP over stdio (and streamable HTTP via dist/http.js). Test it with the MCP Inspector:
npx @modelcontextprotocol/inspector node dist/stdio.jsLicense
MIT. Copyright (c) 2026 Walma AI AB.
Available Tools
5 toolscompare_periodsB
Compare two date ranges side by side with deltas.
With no dimension, returns site-wide totals for both periods. With a dimension (query, page, country, device), returns the top rows by current clicks with previous-period values and deltas; rows that only exist in one period are included with zeros for the other.
Inputs: site (required), current_end (required), previous_end (required), current_start (required), +5 more. Returns: object
inspect_urlB
Run URL Inspection for a page: index status, coverage verdict, canonical (Google vs user), last crawl, robots/indexing state, mobile and rich-result verdicts. Quota: 2000 calls/day per property. Requires Owner or Full access.
Inputs: url (required), site (required), language. Returns: object
list_sitemapsB
List submitted sitemaps for a property with status, last download, errors/warnings and indexed URL counts.
Inputs: site (required). Returns: result
list_sitesA
List Search Console properties the service account has access to, with the permission level for each.
Inputs: no named parameters. Returns: result
search_analyticsA
Query Search Analytics (clicks, impressions, CTR, position).
Args: site: Property URL, e.g. 'sc-domain:example.com' or 'https://example.com/'. start_date / end_date: YYYY-MM-DD. Defaults to the last 28 days ending 2 days ago. dimensions: Any of date, query, page, country, device, searchAppearance. Omit for site-wide totals. row_limit: 1-25000 (default 100). Use start_row to paginate. filters: List of {"dimension": "query|page|country|device|searchAppearance", "operator": "equals|contains|notContains|includingRegex|excludingRegex", "expression": "..."}. Multiple filters are ANDed. search_type: web (default), image, video, news, discover, googleNews.
Inputs: site (required), filters, end_date, row_limit, +4 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct purpose: list_sites, search_analytics, compare_periods, list_sitemaps, inspect_url. Potential minor confusion between search_analytics and compare_periods (both query analytics data), but descriptions clarify the difference (single vs two periods).
All tool names follow a consistent verb_noun pattern (list_sites, search_analytics, compare_periods, list_sitemaps, inspect_url). No deviations or mixing of conventions.
5 tools is well-scoped for a Google Search Console server, covering core operations without bloat. Each tool serves a clear purpose.
Covers listing sites, analytics, sitemaps, and URL inspection, but missing operations for managing sitemaps (submit, delete) and site property management (add, delete). These gaps could cause agent dead ends for common tasks.
Related MCP Connectors
Read-only Google Search Console MCP server for AI assistants.
Google Search Console, GA4 and PageSpeed MCP server for Claude, ChatGPT and Cursor. Free, hosted.
Ask Google Search Console in plain language. Hosted, free, no Google Cloud project.
Multi-tenant GSC data fetcher for AI agents. OAuth secured.
Related MCP Servers
- AlicenseBqualityAmaintenanceModel Context Protocol (MCP) server that provides AI agents with access to Google Search Console data.251,377 npm322MIT
- AlicenseNot gradedqualityCmaintenanceSelf-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.2MIT
- AlicenseNot gradedqualityNot gradedmaintenanceSelf-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