Skip to main content
Glama
Google Search Console MCP server

Google Search Console MCP server

by Walma-Labs

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

list_sites

Properties the service account can see, with permission level

search_analytics

Clicks, impressions, CTR and position by date, query, page, country, device or search appearance, with filters and pagination

compare_periods

Two date ranges side by side with deltas, site-wide or per dimension

list_sitemaps

Submitted sitemaps with status, errors and indexed counts

inspect_url

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

  1. In Google Cloud Console, pick or create a project.

  2. Enable the Google Search Console API (searchconsole.googleapis.com).

  3. IAM & Admin → Service accounts → Create. No project roles are needed.

  4. 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_periods and list_sitemaps.

  • inspect_url needs 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-mcp

Claude 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.js

It 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-mcp

In 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/mcp indexed, 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.js

The server speaks MCP over stdio (and streamable HTTP via dist/http.js). Test it with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/stdio.js

License

MIT. Copyright (c) 2026 Walma AI AB.

Available Tools

5 tools
compare_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

    A3.6/5.0

    Scored across 5 tools

    Disambiguation4/5

    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).

    Naming Consistency5/5

    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.

    Tool Count5/5

    5 tools is well-scoped for a Google Search Console server, covering core operations without bloat. Each tool serves a clear purpose.

    Completeness3/5

    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

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      Model Context Protocol (MCP) server that provides AI agents with access to Google Search Console data.
      25
      1,377 npm
      322
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Self-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.
      2
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Self-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
    • A
      license
      B
      quality
      C
      maintenance
      A 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.
      20
      MIT