# acamolese/google-search-console-mcp [Health: Active]

**Category:** 🎯 Marketing  
**Repository:** https://github.com/acamolese/google-search-console-mcp  
**GitHub Stars:** 11  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/acamolese-google-search-console-mcp

## Description
Google Search Console MCP server: query performance data, inspect URLs, check indexing, and generate brandable HTML SEO audit reports with a 30/60/90-day roadmap. Read-only OAuth scope, installable via uvx mcp-google-search-console.

## Tools
Capabilities this server exposes over MCP:

- **gsc_sites** — List every property the authenticated account can read.

        Call this first when a property string fails: it returns the exact `site_url`
        values the other tools expect, and whether each one is a domain property
        (`sc-domain:example.com`) or a URL-prefix property.
        
- **gsc_site_details** — Permission level and property type for one property.
- **gsc_query** — Query the Search Analytics report: clicks, impressions, CTR, position.

        This is the general-purpose tool. With no dates it covers the last 28 days
        ending today (UTC), with data_state=all so today's partial data is included,
        matching what the Search Console UI shows.

        Example: site_url="sc-domain:example.com", dimensions="query,page",
        period="last_28_days", row_limit=100.

        Returns a `# meta ...` line then a TSV table, or JSON with `meta` and `rows`.
        The meta names the exact range, the row count, whether more rows exist and
        the `start_row` to pass next.
        
- **gsc_performance_overview** — Site totals for a period, compared with a baseline by default.

        Start here: it answers "is the site up or down" in one call, with the
        percentage change on every metric. `position_delta` is negative when the
        average position improves. With a comparison, a rolling window ends on the
        last day with final data (`data_through`), so both sides hold whole days.
        
- **gsc_compare_periods** — Join two periods on one dimension and rank the rows by click delta.

        Answers "what changed" without the model diffing two tables by hand. Rows
        present in only one period are kept, with zeros on the missing side; the
        biggest movers in both directions are returned, worst first. The meta counts
        how many rows gained and how many lost clicks. When a side was read only up
        to its row limit, the meta flags it: a row missing there may only be below
        the cut.
        
- **gsc_quick_wins** — Queries close enough to the top that a push would pay off.

        Ranked by the clicks each query would gain at `target_position`, not by
        impressions: a big query already near its ceiling is not an opportunity.
        The meta reports the thresholds that were applied.
        
- **gsc_ctr_gaps** — Rows that rank well but are clicked far less than their position implies.

        The snippet, not the ranking, is the problem, which makes these the
        cheapest fixes available. `expected_ctr` is what a result at that position
        normally earns.
        
- **gsc_cannibalization** — Queries where several pages of the site compete for the same result.

        Leaves out brand queries (pass `brand_terms`), queries where one page sits
        in the top three with most of the clicks, and queries below the impression
        threshold. Reads up to 25,000 query/page pairs; the meta says when the tail
        was cut off.
        
- **gsc_traffic_drops** — Pages that lost clicks against the baseline, each with a likely cause.

        `diagnosis` tells a ranking loss from fewer impressions at a stable position,
        a collapsed CTR and a page gone from the results: they need different fixes,
        and both periods' numbers are in the row. Rolling windows end on the last day
        with final data (`data_through` in the meta); `compare=year` handles seasonality.
        
- **gsc_content_decay** — Pages sliding down month after month.

        A period comparison hides this: a page that halves over six months never
        shows a sharp drop in any single month-on-month check. Only whole calendar
        months are compared, so the month in progress is left out (`last_month` in
        the meta). One query per month runs in parallel.
        
- **gsc_alerts** — What changed sharply enough to be worth a message today.

        Compares the last `window_days` against the window before (or a year
        earlier) across queries and pages, and returns only movements past fixed
        alerting rules, listed in the meta: lost positions, collapsed CTR, dropped
        or vanished pages. The window ends on the last day with final data.
        
- **gsc_portfolio** — Every accessible property at a glance, ranked worst first.

        One row per property with the current period, the previous one and a health
        flag: critical below -30% clicks, warning below -15%. Use it to decide which
        property to look at before running anything else.
        
- **gsc_brand_split** — Brand, non-brand and undisclosed clicks, month by month.

        Computed over every query with server-side regex filters, so no row limit
        applies. `anonymized` is what Google counts but never shows as a query; it
        belongs to neither side. Whole months only: the month in progress is left out.
        
- **gsc_indexing_issues** — Check whether a batch of URLs is indexed, and why not when they are not.

        Runs the inspections concurrently and returns one row per input URL, in input
        order. A URL that fails gets an `error` column instead of a verdict; the rest
        of the batch still comes back. For the full payload of a single page
        (mobile usability, rich results, AMP) use `gsc_inspect_url`.

        Quota: 600 inspections per minute and 2,000 per day, per property.

        Columns: url, verdict (PASS / PARTIAL / FAIL / NEUTRAL), coverage_state,
        robots_txt_state, indexing_state, page_fetch_state, crawled_as,
        last_crawl_time, google_canonical, user_canonical, error. The meta carries a
        verdict summary.
        
- **gsc_inspect_url** — Full URL Inspection for one page: index, mobile, rich results and AMP.

        Use this when one page needs a diagnosis. For an indexed-or-not sweep across
        many URLs use `gsc_indexing_issues`.

        Quota: 600 inspections per minute and 2,000 per day, per property.
        
- **gsc_sitemaps** — List the sitemaps Google knows about for a property, with errors and warnings.

        Read-only: submitting or deleting a sitemap needs the read-write scope, which
        this server never requests.

        Returns one row per sitemap: path, last submitted and downloaded timestamps,
            pending flag, index flag, warning and error counts, and the submitted /
            indexed URL counts when Google reports them.
        
- **gsc_doctor** — Report the server's configuration and whether Search Console answers.

        Call this first when something fails: it names the auth mode in use, when the
        token expires, how many properties the account can read, the cache state and
        the defaults every other tool applies. Secrets are masked.
        
- **gsc_audit** — Build a complete, self-contained HTML SEO audit for one property.

        Collects the period and its baseline (previous period or a year earlier),
        top queries and pages, devices, countries, the daily trend, six complete
        months of history, brand totals, sitemaps and an indexing check, then detects
        issues and builds a prioritised strategy and roadmap. Sections that could not
        be fetched are named, never shown as clean. English and Italian.

        Ask the user for the period if they have not named one: the 28-day default
        is rarely what a client report wants.

        Returns a compact JSON summary first (KPIs with deltas, issue counts, top
        quick wins, roadmap), so the findings can be discussed without reading the
        HTML, followed by the report path or the document itself.
        

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "google-search-console-mcp": {
    "command": "uvx",
    "args": ["mcp-google-search-console"],
    "env": {
      "GSC_CLIENT_ID": "",
      "GSC_CLIENT_SECRET": "",
      "GSC_REFRESH_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `GSC_CLIENT_ID`, `GSC_CLIENT_SECRET`, `GSC_REFRESH_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation & README

<!-- mcp-name: io.github.acamolese/google-search-console-mcp -->

# Google Search Console MCP

**English** · [Italiano](https://github.com/acamolese/google-search-console-mcp/blob/HEAD/README.it.md)

[![CI](https://github.com/acamolese/google-search-console-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/acamolese/google-search-console-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/mcp-google-search-console)](https://pypi.org/project/mcp-google-search-console/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-google-search-console)](https://pypi.org/project/mcp-google-search-console/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

Eighteen read-only tools over the Google Search Console API, plus a deterministic
white-label HTML audit report an agency can put its own name on and send to a
client, in English or Italian.

![The generated audit report](https://raw.githubusercontent.com/acamolese/google-search-console-mcp/HEAD/docs/report-preview.png)

Regenerate that report from committed synthetic data, with no credentials:

```bash
python scripts/render_sample_report.py --lang en --open
```

## What's new in 4.0

4.0 is about trust: every number the server reports now says what it is based on,
and nothing incomplete is presented as a finding.

- **Comparisons hold whole days.** Search Console's latest days are partial for a
  while, so a 7-day window ending today used to start 15-20% down against the week
  before. Comparison tools now end rolling windows on the last day with final data
  and report it as `data_through`.
- **Year over year.** `compare="year"` on the overview, period comparison, traffic
  drops, alerts and the audit. Whole months map to the same months last year;
  other ranges move back 52 weeks so weekdays line up.
- **Filters everywhere.** The analysis tools and `gsc_compare_periods` accept the
  same `filters` and `type` as `gsc_query`: analyse `/blog/`, one country, mobile
  only, or Discover.
- **Brand vs non-brand, done properly.** The new `gsc_brand_split` tool, and the
  audit, compute the split over every query with server-side regex filters and
  report the clicks Google does not disclose as a third share. Brand terms match
  whole words only.
- **No more false alarms.** Content decay compares complete months only. A page
  below a row limit is no longer reported as lost. A failed URL Inspection is no
  longer an indexing problem. Cannibalisation leaves out brand queries and queries
  one page clearly owns.
- **A sounder report.** One definition of a low CTR, thresholds per kind of row,
  inspection of the pages that lost clicks, a "pages in steady decline" section, a
  "how to read this report" section, translated verdicts, darker default colours
  and accessible charts and tables. The pagination advice no longer recommends
  canonicalising to page one.

Upgrading from 3.x: see the breaking changes at the top of the
[changelog](https://github.com/acamolese/google-search-console-mcp/blob/main/CHANGELOG.md#400---2026-11-14).

## Install

### Claude Code

```bash
/plugin marketplace add acamolese/google-search-console-mcp
/plugin install google-search-console@acamolese
```

The plugin brings the MCP server, five skills (weekly review, cannibalisation
check, indexing audit, content opportunities, white-label client audit) and a
config prompt for the three credentials.

### Claude Desktop

Download `google-search-console.mcpb` from the
[latest release](https://github.com/acamolese/google-search-console-mcp/releases)
and open it. It needs [uv](https://docs.astral.sh/uv/) installed. Or edit the
config file directly:

```json
{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"],
      "env": {
        "GSC_CLIENT_ID": "...",
        "GSC_CLIENT_SECRET": "...",
        "GSC_REFRESH_TOKEN": "..."
      }
    }
  }
}
```

### Cursor, Codex, Gemini CLI, Zed

Any MCP client takes the same three lines: command `uvx`, argument
`mcp-google-search-console`, and the three `GSC_*` environment variables.

```bash
# Codex
codex mcp add google-search-console -- uvx mcp-google-search-console

# Gemini CLI
gemini mcp add google-search-console uvx mcp-google-search-console
```

### Docker

```bash
docker build -t mcp-gsc .
docker run --rm -p 127.0.0.1:8765:8765 \
  -e GSC_CLIENT_ID -e GSC_CLIENT_SECRET -e GSC_REFRESH_TOKEN \
  -v "$PWD/reports:/reports" mcp-gsc
```

The container speaks streamable HTTP on `/mcp`. It has no authentication of its
own: keep it on loopback or behind a reverse proxy.

## Authentication

The OAuth scope is `webmasters.readonly` and nothing else. No tool in this server
can modify a property, a sitemap or anything else in Search Console.

Credentials are resolved in this order:

1. `GSC_AUTH_MODE` if set (`oauth`, `service_account`, `adc`)
2. `GSC_SERVICE_ACCOUNT_FILE` or `GSC_SERVICE_ACCOUNT_JSON`
3. `GSC_CLIENT_ID` + `GSC_CLIENT_SECRET` + `GSC_REFRESH_TOKEN`
4. A token file in `~/.config/mcp-google-search-console/`
5. Application Default Credentials

### OAuth, once

1. In [Google Cloud Console](https://console.cloud.google.com/), enable the
   **Google Search Console API** and create an OAuth client of type
   **Desktop app**.
2. Export the client, or save the downloaded JSON as
   `~/.config/mcp-google-search-console/oauth_credentials.json`:

   ```bash
   export GSC_CLIENT_ID="...apps.googleusercontent.com"
   export GSC_CLIENT_SECRET="..."
   uvx mcp-google-search-console auth
   ```

3. The browser flow stores a token at
   `~/.config/mcp-google-search-console/token.json` with `0600` permissions.
   Secrets are never printed by default; add `--print-env` to also get the three
   `export` lines for a stateless setup.

On a headless machine, run `auth --print-env` on your laptop and copy the three
environment variables across. `--no-browser` prints the URL instead of opening one, but still
needs a local redirect.

### Service account

Grant the service account's email read access to the property in Search Console,
then point the server at the key:

```bash
export GSC_SERVICE_ACCOUNT_FILE=/path/to/key.json
# or, for a container:
export GSC_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'
```

### Check it works

```bash
uvx mcp-google-search-console doctor
```

Prints the auth mode in use, when the token expires, how many properties the
account can read, and the defaults every tool applies. Secrets are masked. Exits
1 when nothing resolves, which is the answer to most "the server won't start"
reports.

## Tools

| Tool | What it answers |
|---|---|
| `gsc_sites` | Which properties can this account read, and in what exact format |
| `gsc_site_details` | Permission level and type for one property |
| `gsc_query` | The Search Analytics report, with filters, dimensions and pagination |
| `gsc_performance_overview` | Is the site up or down, against the previous period or last year |
| `gsc_compare_periods` | What changed between two periods, ranked by click delta |
| `gsc_quick_wins` | Queries close enough to the top that a push would pay off |
| `gsc_ctr_gaps` | Pages that rank but are not clicked |
| `gsc_cannibalization` | Queries where several pages compete against each other |
| `gsc_traffic_drops` | Pages that lost clicks, with a likely cause for each |
| `gsc_brand_split` | Brand, non-brand and undisclosed clicks, month by month |
| `gsc_content_decay` | Pages sliding down month after month |
| `gsc_alerts` | What moved sharply enough to be worth a message today |
| `gsc_portfolio` | Every property at a glance, worst first |
| `gsc_indexing_issues` | Which of these URLs are indexed, and why not |
| `gsc_inspect_url` | Full URL Inspection for one page |
| `gsc_sitemaps` | Which sitemaps Google knows about, with errors and warnings |
| `gsc_doctor` | What is configured, and does the API answer |
| `gsc_audit` | The full HTML report |

Three prompts wrap the workflows that repeat: `gsc_weekly_report`,
`gsc_indexing_audit`, `gsc_content_opportunities`.

## Why this server

| | Here | Typical GSC MCP server |
|---|---|---|
| Client-ready report | Self-contained HTML, English or Italian, white-label | none |
| Analysis | Cannibalisation, CTR gaps, decay, drop diagnosis, brand split, run server-side | raw rows, analysed by the model |
| Honesty | Truncation, skipped sections and anchors declared in every response | silent gaps |
| Thresholds | Adapt to the size of the property | fixed, or none |
| Dates | `period="last_month"`, `days=28`, resolved server-side | explicit dates only |
| Freshness | `gsc_query` matches the UI; comparisons end on the last day with final data | windows that end on partial days |
| Auth | OAuth, service account, ADC | OAuth only |
| Output | TSV by default, roughly a third of the tokens of pretty JSON | `json.dumps(indent=2)` |
| Errors | Google's reason plus what to do about it | bare HTTP status |
| Tests | 350+, on both `mcp` majors, three operating systems | usually none |

## Report customisation

Colours, logo, report name, brand terms and thresholds come from a JSON file.
Pass `branding_path`, or place it at
`~/.config/mcp-google-search-console/branding.json` to apply it everywhere:

```json
{
  "brand_name": "Your Agency",
  "logo": "logo.png",
  "brand_terms": ["clientbrand", "client brand"],
  "colors": { "primary": "#2b6cb0", "primary_dark": "#1a365d" },
  "thresholds": { "min_impressions": 200 }
}
```

A local logo is base64-encoded into the document. A remote one is only kept if
`allow_external_fonts` is true, because the report is otherwise guaranteed to
contain no external URL at all: no CDN, no font service, nothing that phones home
when a client opens it.

`brand_terms` matters more than it looks. Without it, the first label of the
domain is used as the brand, which is wrong for abbreviations, holding companies
and invented names, and it silently mislabels the brand/non-brand split. The
report says when it had to guess.

## Quotas and limits

- **16 months** of daily data. Anything older is not available at any price.
- **Hourly data**: the last 10 days only.
- **URL Inspection**: 600 per minute and **2,000 per day per property**. This is
  the limit that bites on a large site.
- **Search Analytics**: 1,200 queries per minute per site. Responses are cached
  in memory for 6 hours (1 hour for inspections); `no_cache=true` bypasses it.
- **Rows**: 25,000 per API call. Tools default to 100 and cap at 1,000, with
  `start_row` for pagination; the cap is reported in the response, never applied
  silently.

## Environment variables

| Variable | Default | Purpose |
|---|---|---|
| `GSC_CLIENT_ID`, `GSC_CLIENT_SECRET`, `GSC_REFRESH_TOKEN` | | Stateless OAuth |
| `GSC_SERVICE_ACCOUNT_FILE`, `GSC_SERVICE_ACCOUNT_JSON` | | Service account |
| `GSC_AUTH_MODE` | auto | Force `oauth`, `service_account` or `adc` |
| `GSC_REPORT_LANGUAGE` | `en` | Report language: `en` or `it` |
| `GSC_DATA_STATE` | `all` | `all` includes today's partial data, `final` does not |
| `GSC_CACHE_TTL_SECONDS` | `21600` | Response cache TTL; `0` disables it |
| `GSC_INSPECT_CONCURRENCY` | `5` | Parallel URL inspections |
| `GSC_LOG_LEVEL` | `WARNING` | Logging, always to stderr |
| `MCP_TRANSPORT`, `MCP_HOST`, `MCP_PORT` | `stdio` | Transport |

## Troubleshooting

**`spawn uvx ENOENT`** — the client cannot find `uvx` on its PATH. GUI apps do
not inherit a shell PATH. Use the absolute path: `which uvx` gives it, typically
`/Users/you/.local/bin/uvx`.

**`403 forbidden` on every call** — almost always the property format. A domain
property is `sc-domain:example.com`; a URL-prefix property is
`https://example.com/`, trailing slash included. `gsc_sites` returns the exact
strings.

**`401 invalid_grant`** — the refresh token was revoked or expired. Google expires
refresh tokens for OAuth apps still in "testing" after seven days; publish the
app, or re-run `auth`.

**`403 quotaExceeded`** — the daily URL Inspection quota is gone. It resets
tomorrow; nothing retries past it.

**Empty report on a small site** — check the thresholds in the response meta. They
adapt to the property, but the floors (50 impressions, 10 clicks) still apply.
Pass `thresholds` to lower them.

**Anything else** — run `doctor` and include its output in the issue.

## Security

- Read-only scope, requested and never widened.
- Token files are written atomically with `0600` permissions. Credentials supplied
  through the environment are never written to disk.
- `gsc_doctor` masks the client ID and never returns a token.
- No telemetry, no analytics, no request to any host other than Google's API.

See [SECURITY.md](https://github.com/acamolese/google-search-console-mcp/blob/HEAD/SECURITY.md) for the reporting policy.

## Development

```bash
uv venv && uv pip install -e ".[dev]"
ruff check src tests scripts && ruff format --check src tests scripts
pytest -q --cov=google_search_console_mcp
python scripts/sync_versions.py
python scripts/render_sample_report.py --lang it --open
```

Tests never hit the network. Live tests exist behind `-m live` and require
`GSC_LIVE_TESTS=1` plus credentials; they never run in CI.

Releases: see [docs/RELEASING.md](https://github.com/acamolese/google-search-console-mcp/blob/HEAD/docs/RELEASING.md). Decisions not covered by the
code are logged in [docs/DECISIONS.md](https://github.com/acamolese/google-search-console-mcp/blob/HEAD/docs/DECISIONS.md).

## License

MIT. Chart.js 4.5.1 is vendored under `src/google_search_console_mcp/static/`,
also MIT, with its licence alongside.

