seo-analytics-mcp

Google Search Console, GA4 and IndexNow — as an MCP server.

Ask Claude about your own sites. What's ranking, what changed, what's indexed, what's converting.

"Which pages lost the most clicks in the last 28 days versus the 28 before?"
"How is /pricing doing?"
"Is https://example.com/new-post indexed yet?"
"Which pages rank on page one but get almost no clicks?"
"Top 20 queries for the blog last month, and which of them convert in GA4."

You authorise your own Google account against an OAuth client in your own Google Cloud project. Nothing about your access flows through anyone else, this repository contains no credentials, and every Google quota you spend is your own.

Contents

Install · Setup · The seven-day problem · Tools · Response shape · Configuration · Writes · Profiles · Design · Troubleshooting · Development

Related MCP server: GSC Analyst Connector

Install

Requires Python 3.10+ and uv.

uvx seo-analytics-mcp doctor      # no install needed — prints your setup steps, in order

doctor is the whole onboarding experience. It tells you exactly what is missing and what to run next, at every stage. If you read nothing else here, run that.

Setup

Six clicks in the Google Cloud console, then one command. Ten minutes, once.

Create a Google Cloud project — or reuse one. console.cloud.google.com/projectcreate

Enable the APIs. Search Console is required; the GA4 pair is optional.

searchconsole · analyticsdata · analyticsadmin

Configure the consent screen, then press Publish app. console.cloud.google.com/auth/overview

Choose External and publish. You are the only user of your own app, so Google's personal-use exception applies and no verification is needed. Workspace users can choose Internal instead.

Do not skip the Publish step — see below.

Create an OAuth client of type Desktop app and download the JSON. console.cloud.google.com/auth/clients

A Web application client cannot do the loopback redirect this server needs. doctor checks for this specific mistake, because it is the easy one to make.

Authorise, once, from a terminal:

uvx seo-analytics-mcp auth --client-secret ~/Downloads/client_secret_*.json

Your browser opens. Google says "Google hasn't verified this app" — expected for your own client: Advanced → Continue. The token lands in your profile directory at mode 0600.

Check, then connect:

uvx seo-analytics-mcp doctor      # eleven checks; exit 0 means it will work

Connect it

claude mcp add seo \
  -e GSC_DEFAULT_SITE=sc-domain:example.com \
  -e GA4_DEFAULT_PROPERTY=properties/123456789 \
  -- uvx seo-analytics-mcp

{
  "mcpServers": {
    "seo": {
      "command": "uvx",
      "args": ["seo-analytics-mcp"],
      "env": {
        "GSC_DEFAULT_SITE": "sc-domain:example.com",
        "GA4_DEFAULT_PROPERTY": "properties/123456789"
      }
    }
  }
}

Then quit Claude Desktop completely (⌘Q — closing the window is not enough) and reopen.

The seven-day problem

The fix is one click: on the consent screen, set the audience to External and press Publish app. Then uvx seo-analytics-mcp auth --reauth.

doctor flags a token young enough to still be a Testing token, and every invalid_grant error from the server explains this in full. It is not a bug in the server — but it will be the most common issue filed against it.

Tools

Thirteen tools: ten map to upstream operations, two join sources, and one exists purely so the model can tell a confused user what to do.

What a response looks like

Every read tool returns the same four keys. Bounded, self-describing, and carrying its own caveats.

{
  "summary": {
    "source": "gsc",
    "rows_returned": 10,        // what you see
    "rows_matched": 1847,       // what exists upstream
    "date_range": "2026-07-29..2026-08-25",   // resolved, always echoed
    "data_state": "final",
    "totals": { "clicks": 4730, "impressions": 512903, "ctr": 0.0092, "position": 12.4 }
  },
  "rows": [ /* capped at min(row_limit, 1000) */ ],
  "notes": [
    "Google anonymises rare queries: these rows do NOT sum to property totals.",
    "dataState=final excludes the most recent 2-3 days.",
    "1837 further rows were not included inline."
  ],
  "export": "~/.../exports/a1b2c3.csv"        // only when rows spilled
}

Three conventions hold everywhere:

Totals cover every row fetched, not just the rows shown — a model that sees ten rows and a total for ten cannot tell truncation from reality. Rates are never averaged: ctr is recomputed from clicks ÷ impressions, position is impression-weighted, engagementRate is engaged ÷ sessions.

Caveats travel with the data. Whichever layer knows the caveat appends it: the client knows the query dimension was requested, shape() knows how many rows it dropped, GA4 knows the response was sampled. Docstrings alone lose them exactly when the model is looking at the numbers.

Errors name the fix. A 403 tells you which grant to check and where — never a raw Google error body.

The authorised Google account has no access to sc-domain:example.com. Confirm the
account you authorised is the one with access — Search Console grants are per-property
under Settings > Users and permissions, GA4 grants are per-property under Admin >
Property access management. If access was added recently, run `seo-mcp auth --reauth`.

Configuration

Every variable is optional. Precedence: tool argument → environment → profile config.json.

Dates

Every date argument accepts YYYY-MM-DD, today, yesterday or NdaysAgo. Responses echo the absolute range they actually used, because a model that guesses today's date wrong produces an empty result that reads as "traffic went to zero".

Search Console lags 2–3 days and retains ~16 months; ranges outside those bounds are flagged or refused rather than silently returning nothing. GA4 reports in the property's own timezone, so its dates do not line up exactly with Search Console's — the responses say so where it matters.

Writes

Two tools act on the world outside your machine. Both are deliberately awkward.

Read-only scopes are the default. A stranger installing an SEO tool that immediately asks for permission to modify their Search Console properties will reasonably decline.

Profiles

Several Google accounts on one machine — for agencies holding client properties side by side.

uvx seo-analytics-mcp auth --profile client-a --client-secret ./client-a.json
uvx seo-analytics-mcp auth --profile client-b --client-secret ./client-b.json
uvx seo-analytics-mcp profiles list

Set SEO_MCP_PROFILE per MCP server entry. Cache keys include the profile, so two accounts can never serve each other's data.

A profile is one directory — the first thing you will ever ask a user to delete:

uvx seo-analytics-mcp profiles rm client-a --yes

They live in ~/Library/Application Support/seo-mcp/ (macOS), $XDG_CONFIG_HOME/seo-mcp/ (Linux) or %APPDATA%\seo-mcp\ (Windows).

Design

Four layers, strictly downhill. Get this wrong and the auth flow ends up inside a tool call, which is the failure the whole design exists to prevent.

flowchart TD
    subgraph L4["Entry points"]
        S[server.py<br/><i>MCPServer, stdio</i>]
        C[cli.py<br/><i>auth · doctor · profiles · serve</i>]
    end
    subgraph L3["Tools — argument surface, docstrings, cache policy"]
        T[13 handlers<br/><i>no HTTP, no credentials, no row shaping</i>]
    end
    subgraph L2["Clients — the only modules that speak HTTP"]
        G[gsc.py]
        A[ga4.py]
        I[indexnow.py]
    end
    subgraph L1["Leaves — importable by anyone, import nobody"]
        LV[shaping · errors · config · cache · auth/store · auth/scopes]
    end
    F[auth/flow.py<br/><i>loopback + PKCE · opens a browser</i>]

    S --> T
    C --> T
    C -.->|only reachable from here| F
    T --> G & A & I
    G & A & I --> LV

The browser flow must never run inside a tool call. An MCP tool that blocks on stdio waiting for a human to finish a consent screen looks like a hung server, and the model has no way to help. One CLI command, run once, is the whole difference — and a test walks the AST of every module to enforce it.

Other rules the tests enforce mechanically: shaping.py imports no Google library (which is why the row logic is fully unit-testable with no credentials), tools import no HTTP library, and nothing on the server path calls print() — on a stdio transport, stdout carries JSON-RPC and a single stray print corrupts the stream.

Troubleshooting

Every issue report should include seo-mcp doctor --json. It contains no credentials — only paths, versions, which checks passed and which APIs answered.

Development

uv sync --extra dev
uv run pytest -q                    # 147 tests · no credentials · no network
uv run python scripts/smoke.py      # drives the server over real stdio JSON-RPC
uv run ruff check src tests

python3 -m venv .venv && ./.venv/bin/pip install -e ".[dev]"
./.venv/bin/python -m pytest -q
./.venv/bin/python scripts/smoke.py ./.venv/bin/seo-mcp

scripts/smoke.py starts the server as a subprocess, completes the MCP handshake, lists the tools and calls several — using a throwaway profile directory, so your real token is untouched. It is the fastest way to confirm the protocol side works before any Google credential exists.

To poke at it by hand, the MCP Inspector needs nothing beyond Node:

npx @modelcontextprotocol/inspector ./.venv/bin/seo-mcp            # web UI
npx @modelcontextprotocol/inspector --cli ./.venv/bin/seo-mcp \
    --method tools/call --tool-name auth_status                    # scriptable

Not covered by automated tests: the OAuth flow itself and live IndexNow submission. Both need a human and a real domain, and mocking them would only test the mock. They belong in a short manual release checklist.

Two things it will not do

Contributing

Issues and pull requests welcome. The credential-free test suite runs on every push across Linux, macOS and Windows on Python 3.10 and 3.13 — if it passes locally it will pass in CI.

Renaming a tool or changing an argument breaks every saved prompt a user has. Those changes go in CHANGELOG.md and are a minor bump before 1.0, a major one after.

Licence

MIT.