flin Google Search Console MCP

In Claude Desktop starten — Mac mit Apple Silicon (M1 oder neuer)

1. Desktop-Paket herunterladen und in Claude Desktop unter Einstellungen → Erweiterungen → Erweiterung installieren importieren.

2. Google OAuth Client ID und Google OAuth Client Secret aus dem Passwortmanager bzw. vom zuständigen Administrator eintragen. Optional: die freigegebene Standard-Property. Die Werte gehören zu einem Google-OAuth-Client vom Typ Desktop-App; die Search Console API muss aktiviert sein.

3. In Claude: „Führe connection_status aus.“ Das prüft die lokale Einrichtung, öffnet keinen Browser und ruft Google nicht auf. Bei incomplete zuerst die Einstellungen vervollständigen.

4. Danach ausdrücklich: „Führe list_sites aus und prüfe, ob meine freigegebene Property angezeigt wird.“ Bei Bedarf Google-Anmeldung im Browser abschliessen. Nur ein erfolgreicher Google-Aufruf bestätigt den Zugriff; ein vorhandenes Token genügt dafür nicht.

5. Für den konkreten Datentest: „Zeige mit get_site_summary die Klicks und Impressionen meiner ausgewählten Property für die letzte abgeschlossene Woche.“ Verwende die Property exakt aus list_sites. Ergebnisse können vertrauliche Daten enthalten.

Windows und Intel-Macs bleiben unterstützt; Linux kann den Python-Server direkt nutzen. Ein automatisierter Paketstart auf Apple Silicon ersetzt keinen echten Kundenkontotest in der Claude-Oberfläche.

Related MCP server: google-search-console-mcp-python

Updates und Verbindungsstatus

• Erweiterungsversion: Version des importierten Starters in Claude.

• Serverversion: connection_status.server_version bzw. health_check.server_version.

• Der aktuelle Starter übernimmt bei Neustart stabile PyPI-Updates innerhalb >=0.1.8,<0.2 mit Python 3.12. Vorabversionen und 0.2/1.x sind ausgeschlossen. Laufende Sitzungen, OAuth-Einstellungen und gespeicherte Tokens bleiben erhalten.

• Einmaliger Import des aktuellen Pakets ist für ältere Starter nötig, damit die Versionsgrenze und das neue Tool-Verzeichnis gelten. Normale kompatible Server-Updates brauchen danach keinen Paketimport. Änderungen am Starter, an Eingabefeldern oder der Python-Anforderung können einen neuen Import verlangen.

• Start benötigt normalerweise Internet. Bei Startproblemen: Verbindung prüfen und Claude neu starten; den Cache nicht löschen. Der dokumentierte manuelle Cache-Fallback ist nur für bereits geladene Pakete verfügbar. Google-Abfragen benötigen weiterhin Internet.

connection_status liefert nur server_version, configuration_status, auth_status, live_access und next_step. Gespeicherte gültige oder erneuerbare Tokens ergeben auth_status=unknown, solange Google nicht geprüft wurde. live_access bleibt bei diesem rein lokalen Tool immer not_checked; list_sites ist ein separater Live-Test und ändert diese lokale Statusaussage nicht. Das bestehende health_check und seine Felder bleiben erhalten.

Datenumfang und Rechte

Der Server liest Daten; er ändert keine Properties und beantragt keine Indexierung. Performance-Leserechte genügen für Performance-Abfragen; für den vollständigen Funktionsumfang einen Full User verwenden. Eine pauschale Owner-Pflicht besteht nicht. API-Aktivierung und Zugriff auf die konkrete Property sind getrennte Voraussetzungen. Google-Rollen

Search Analytics liefert Top-Zeilen, keinen garantierten Voll-Export. Pro Anfrage sind maximal 25'000 Zeilen möglich (Standard 1'000); start_row ermöglicht weitere Seiten, hebt Googles interne Grenzen aber nicht auf. Google nennt maximal 50'000 Zeilen pro Tag, Property und Suchtyp. Anonymisierte Suchanfragen fehlen in Query-Zeilen; Zeilensummen können deshalb von Gesamtsummen abweichen. Fehlende Zeilen sind kein Nachweis für null Suchanfragen. API-Grenzen · Datenauslassungen

URL Inspection zeigt den Stand im Google-Index, keinen Live-Crawl der Website. Google API

Datenschutz · Sicherheit · Support · Claude Code Plugin · Versionierte Downloads

Administrator and developer setup

If your goal is simply "make this work in Claude Desktop", follow these steps in order.

1) Make sure the Google account has Search Console access

The Google account you use during login must already have access to at least one Search Console property.

The signed-in account needs access to the selected Search Console property. Full-user access is sufficient for the full read-only feature set; owner status is not required. Restricted users can view Performance data and have limited URL Inspection rights. Google Cloud API enablement does not grant property access. See Google's permissions table. The OAuth client must be a Desktop app with the Search Console API enabled; the server requests only webmasters.readonly.

2) Create or choose a Google Cloud project

In Google Cloud:

1. Create a new project or select an existing one.

2. Enable the Google Search Console API for that project.

Official references:

• Search Console API overview

• Search Console API quickstart

3) Configure the OAuth consent screen

In Google Cloud, configure the OAuth consent screen for the same project.

For most personal or team setups:

• choose External

• keep the app in Testing while you validate the integration

• add your own Google account as a test user

Important:

• If the app is External and still in Testing, users must be listed as test users

• Google documents that test-user authorizations in testing mode can expire after 7 days

This MCP only requests one read-only scope:

• https://www.googleapis.com/auth/webmasters.readonly

Official references:

• OAuth 2.0 for Desktop Apps

• OAuth consent screen configuration

• Publishing status and test users

4) Create OAuth credentials of type Desktop app

Create an OAuth client in the same Google Cloud project:

1. Go to Credentials

2. Click Create client

3. Choose Desktop app

4. Copy the generated:

   • client ID

   • client secret

You do not need to manually wire redirect URIs into Claude Desktop for this MCP. The desktop OAuth flow uses a local loopback callback handled by the running MCP process.

5) Add the MCP to Claude Desktop

Recommended: desktop extension

Download flin-google-search-console-mcp-<version>.mcpb from the GitHub releases and open it in a current Claude Desktop version with MCPB UV runtime support. Alternatively, use Install Extension in the desktop extension settings.

Enter the Google OAuth client ID and client secret from step 4 and, optionally, a default property such as sc-domain:example.com. The secret field is marked sensitive. Continue with the login instructions below. Manual JSON editing is not required; the Google Cloud setup in steps 1–4 is still required.

The extension runs locally on macOS and Windows. From installer 0.1.8, it checks PyPI for the newest stable compatible 0.1-series server release every time the server starts. Restart Claude Desktop to apply a published server update; no new installer is needed for ordinary server releases. Running conversations are not hot-updated. Python 3.12 and server packages are managed by uv. Startup requires internet access; the installer contains no credentials or saved tokens.

Already installed 0.1.7 or earlier? Import the current bundle once to apply the compatibility limit and updated extension metadata. Keep the same OAuth settings; tokens remain outside the extension. The extension's displayed version describes the launcher. health_check returns server_version, the actual running PyPI version.

Changes to Claude's extension settings, permissions, launcher or required Python version may still require a new bundle. Claude does not auto-update privately shared manifests from GitHub. A package that drops Python 3.12 support cannot be used by this launcher; uv selects the latest stable version within >=0.1.8,<0.2.

Alternative: manual configuration

The existing PyPI installation remains available. Its minimum configuration is:

{
  "mcpServers": {
    "flin-google-search-console-mcp": {
      "command": "uvx",
      "args": ["--refresh-package", "flin-google-search-console-mcp", "--prerelease", "disallow", "flin-google-search-console-mcp>=0.1.8,<0.2"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_oauth_client_id",
        "GOOGLE_CLIENT_SECRET": "your_oauth_client_secret"
      }
    }
  }
}

If you want a default property so you do not have to pass site_url every time:

{
  "mcpServers": {
    "flin-google-search-console-mcp": {
      "command": "uvx",
      "args": ["--refresh-package", "flin-google-search-console-mcp", "--prerelease", "disallow", "flin-google-search-console-mcp>=0.1.8,<0.2"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_oauth_client_id",
        "GOOGLE_CLIENT_SECRET": "your_oauth_client_secret",
        "GOOGLE_SEARCH_CONSOLE_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

For local development from a checkout:

{
  "mcpServers": {
    "flin-google-search-console-mcp-local": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/flin-google-search-console-mcp",
        "flin-google-search-console-mcp"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your_oauth_client_id",
        "GOOGLE_CLIENT_SECRET": "your_oauth_client_secret"
      }
    }
  }
}

Replace /absolute/path/to/flin-google-search-console-mcp with your local checkout path.

6) Restart Claude Desktop

After saving the MCP configuration, fully restart Claude Desktop so it reloads the local server definition.

7) Complete the first login inside Claude

Start with these prompts:

Run health_check for the Google Search Console MCP and show the full result.

List my Search Console sites.

On the first authenticated tool call, the MCP opens a browser window. Sign in with the Google account that has Search Console access and approve the request.

After that:

• the token is stored locally

• future access tokens refresh automatically

• you do not need to paste a refresh token into Claude Desktop config

What the MCP stores locally

The MCP stores a local token JSON file after the first successful login.

New token directories are created with private permissions. Existing directories keep their permissions; on macOS and Linux, they must belong to the current user and must not be writable by other users. Token files are written with owner-only access.

Default locations:

• macOS: ~/Library/Application Support/flin-google-search-console-mcp/token.json

• Linux: ~/.config/flin-google-search-console-mcp/token.json

• Windows: %APPDATA%\flin-google-search-console-mcp\token.json

If you want to override the location:

{
  "mcpServers": {
    "flin-google-search-console-mcp": {
      "command": "uvx",
      "args": ["--refresh-package", "flin-google-search-console-mcp", "--prerelease", "disallow", "flin-google-search-console-mcp>=0.1.8,<0.2"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_oauth_client_id",
        "GOOGLE_CLIENT_SECRET": "your_oauth_client_secret",
        "GOOGLE_SEARCH_CONSOLE_TOKEN_PATH": "/absolute/path/to/flin-google-search-console-mcp-token.json"
      }
    }
  }
}

Multiple Google accounts

You can connect multiple Google accounts and choose the account per tool call.

By default, named account tokens are stored next to the default token. To choose a dedicated token directory, set GOOGLE_SEARCH_CONSOLE_TOKEN_DIR:

{
  "mcpServers": {
    "flin-google-search-console-mcp": {
      "command": "uvx",
      "args": ["--refresh-package", "flin-google-search-console-mcp", "--prerelease", "disallow", "flin-google-search-console-mcp>=0.1.8,<0.2"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_oauth_client_id",
        "GOOGLE_CLIENT_SECRET": "your_oauth_client_secret",
        "GOOGLE_SEARCH_CONSOLE_TOKEN_DIR": "/absolute/path/to/search-console-tokens"
      }
    }
  }
}

Then pass account in tool calls:

{
  "tool": "list_sites",
  "args": {
    "account": "work"
  }
}

The first call for a new account opens the OAuth browser flow and stores a separate token, for example work.json. Account names may contain only letters, numbers, _, -, and ..

An account name must not resolve to the default token file, including case variants or filesystem aliases. With the default storage layout, token is reserved. Omit account to use the default account. Existing named account files remain supported.

First Prompts To Verify Everything Works

Use these in Claude Desktop after the server is configured.

Health check

Run health_check for the Google Search Console MCP and show the full result.

Confirm available properties

List my Search Console sites and tell me whether sc-domain:example.com is available.

Quick summary

Run get_site_summary for site_url sc-domain:example.com from 2026-04-01 to 2026-04-20 and show clicks, impressions, ctr, and position.

Top queries

Run get_top_queries for site_url sc-domain:example.com from 2026-04-01 to 2026-04-20 with row_limit 25 and show the top queries by clicks.

Top pages

Run get_top_pages for site_url sc-domain:example.com from 2026-04-01 to 2026-04-20 with row_limit 25 and show the top pages by clicks.

URL inspection

Run inspect_url for site_url sc-domain:example.com and inspection_url https://example.com/.

Property Format: Domain vs URL-prefix

This is one of the most common setup mistakes.

Examples:

• Domain property: sc-domain:example.com

• URL-prefix property: https://www.example.com/

Use the exact property string returned by list_sites. Do not guess.

What This MCP Exposes

• connection_status (local, no sign-in or Google request)

• health_check

• list_sites

• get_site_summary

• query_performance

• get_top_queries

• get_top_pages

• get_dimension_breakdown

• inspect_url

Which Tool To Use

Recommended call order:

1. health_check

2. list_sites

3. get_site_summary

4. get_top_queries or get_top_pages

5. query_performance for custom dimensions and filters

6. inspect_url for indexability and canonical checks on a specific URL

Search Analytics Notes

• query_performance uses the Search Analytics API under the hood

• Search Analytics returns top rows, not guaranteed full exports

• The MCP maps Google's positional keys[] rows into named dimensions objects

Supported knobs include:

• dimensions

• filters

• search_type

• aggregation_type

• data_state

• row_limit

• start_row

Example Tool Calls

Site summary

{
  "tool": "get_site_summary",
  "args": {
    "site_url": "sc-domain:example.com",
    "start_date": "2026-04-01",
    "end_date": "2026-04-20"
  }
}

Top queries

{
  "tool": "get_top_queries",
  "args": {
    "account": "work",
    "site_url": "sc-domain:example.com",
    "start_date": "2026-04-01",
    "end_date": "2026-04-20",
    "row_limit": 25
  }
}

Query performance with filters

{
  "tool": "query_performance",
  "args": {
    "site_url": "sc-domain:example.com",
    "start_date": "2026-04-01",
    "end_date": "2026-04-20",
    "dimensions": ["page"],
    "filters": [
      {
        "dimension": "device",
        "operator": "equals",
        "expression": "MOBILE"
      }
    ],
    "row_limit": 50
  }
}

URL inspection

{
  "tool": "inspect_url",
  "args": {
    "site_url": "sc-domain:example.com",
    "inspection_url": "https://example.com/blog/seo-agent"
  }
}

Source Setup

If you want to run the MCP from source:

uv sync --extra dev
cp .env.example .env
# Fill .env values
uv run --env-file .env flin-google-search-console-mcp

Published Package

Run the latest published package directly:

uvx --refresh-package flin-google-search-console-mcp --prerelease disallow "flin-google-search-console-mcp>=0.1.8,<0.2"

Troubleshooting

missing_configuration

• GOOGLE_CLIENT_ID or GOOGLE_CLIENT_SECRET is missing from the MCP config

oauth_required

• no usable token exists yet

• the first browser-based login has not been completed

• the stored refresh token is no longer usable and the browser flow must run again

permission_denied

• the Google account used during login does not have access to the Search Console property

No sites returned

• verify that the Google account really has Search Console access

• confirm you logged into the correct Google account in the browser

Google shows an unverified or testing warning

• this is usually expected while the app is in testing mode

• make sure your Google account is added as a test user on the OAuth consent screen

Security

See the security review for checks, fixes and remaining limitations. Tokens must be private files (0600 on macOS/Linux); legacy token files with broader permissions must be restricted before use. The extension is unsigned; SHA256SUMS verifies download integrity, not publisher identity.

More Docs

• Operational guide

• Testing guide

• Release checklist

• Desktop extension guide

• Directory submission preparation

• Directory reviewer tests

Release on GitHub + PyPI

This repository publishes automatically with GitHub Actions:

• CI: .github/workflows/ci.yml

• Release: .github/workflows/release.yml triggered by git tags v*

CI tests the Python package, desktop bundle and Claude Code plugin on Linux, macOS and Windows. It also checks the plugin manifest and rejects stale copies of the runtime in plugin/. A release tag builds all formats, publishes the Python package to PyPI, verifies the launcher against that published version, and creates a GitHub Release with the .mcpb, plugin ZIP, their checksums and Python distributions. Only Python distributions go to PyPI.

A manual workflow run on a branch only validates and builds downloadable workflow artifacts. Publishing requires a version tag matching the project, package, plugin and lockfile versions. Publishing a directory listing requires the separate process described in the submission guide.

PyPI publication runs automatically for each version tag. To retry publishing an older tag separately, manually run Release on that tag with publish_pypi enabled.

1) Configure PyPI Trusted Publisher

In PyPI project settings for flin-google-search-console-mcp, add a Trusted Publisher with:

• Owner: flin-agency

• Repository: flin-google-search-console-mcp

• Workflow: release.yml

• Environment: pypi

2) Cut a release

Follow the release checklist, commit and push the reviewed changes, then tag the prepared version:

git tag v0.1.8
git push origin v0.1.8