Skip to content

Light version: pages open quickly, without the 3D graphics. You are seeing the light version because the 3D graphics would be slow on this device. The content is the same.

Turn on 3D

Preparing the graphics. This can take a moment on the first visit.

Henry Lõiv

Web design & development

GuideSEO & AI Search 12 min read

Google Search Console MCP: free setup for Claude and Codex

Connect Search Console to Claude or Codex on macOS and Windows. Free local MCP setup, read-only Google access, useful SEO prompts and fixes for common errors.

You can connect Google Search Console to Claude or Codex through a local MCP server and ask questions about your site's Google search performance. You do not need a paid hosted connector for this setup. Google's Search Console API is free, subject to quotas; your normal assistant plan or API charges still apply. Google's API pricing

I connected both Search Console and Google Analytics to my local setup on 4 November 2026. This guide documents the Search Console connection for macOS and native Windows PowerShell, with configuration for Claude Desktop, Claude Code and Codex. You only need to configure the client you use.

The server is AminForou's community mcp-gsc project, published as mcp-search-console. It is separate from Google's official Analytics MCP server. The instructions pin mcp-search-console 0.4.1 and use Python 3.13.

Validation, 4 November 2026: the original macOS integration completed authentication, token refresh, property discovery and a live Search Console report. The Windows instructions and the revised launcher below were reviewed against documentation and source code; they have not been run end to end on Windows. Both paths finish with a real data-access check.

What can you actually ask it?

The useful part is getting your own search data into the conversation before asking for advice.

QuestionData to request first
Which pages are losing search traffic?Clicks and impressions for two comparable periods, followed by query and position changes.
Which titles might need attention?Pages with substantial impressions, their CTR, queries, average positions and device split.
What does Google know about this URL?The URL Inspection result, including stored indexing status and last crawl information where available.

GSC covers performance in Google Search. For what tracked visitors do after arriving—such as sessions, engagement and recorded key events—use Google Analytics MCP alongside it. GSC access does not reveal competitors' private data.

URL Inspection reports Google's stored index information. It cannot live-test a URL's indexability or force Google to index the page. URL Inspection API

Before you start

You need access to a Search Console property, permission to create or use a Google Cloud project, and an installed MCP-capable client. The Cloud project provides the API credentials; it does not grant access to your website's Search Console property.

Use Terminal on macOS or PowerShell on Windows. The Windows examples target native Windows clients and Python. WSL has its own installations and paths; keep this setup within one environment. Install your chosen client first using its official instructions: Claude Code, Claude Desktop or Codex.

1. Install Python, pipx and the server

Follow the section for your operating system. If you have already followed the Analytics guide, you can reuse Python and pipx; the MCP servers still get separate environments.

macOS

With Homebrew installed, run:

brew install python@3.13 pipx
pipx ensurepath

Open a new Terminal window, then install the pinned server:

pipx install --python "$(brew --prefix python@3.13)/bin/python3.13" mcp-search-console==0.4.1

Windows PowerShell

Install Python 3.13 with WinGet:

winget install --exact --id Python.Python.3.13

Close and reopen PowerShell. Then install pipx and add its executable directories to your PATH:

py -3.13 --version
py -3.13 -m pip install --user pipx
py -3.13 -m pipx ensurepath

Close and reopen PowerShell again before using the plain pipx command:

pipx --version
pipx install --python (py -3.13 -c 'import sys; print(sys.executable)') 'mcp-search-console==0.4.1'

The py -3.13 selector avoids accidentally installing into a different Python version. If WinGet is unavailable, use the official Python 3.13 Windows installer with pip and the Python launcher enabled, then continue from the pipx commands. Python on Windows · WinGet package · pipx installation

2. Enable the API and download OAuth credentials

In Google Cloud Console:

  1. Create or select a project. You may reuse the Analytics project's credentials infrastructure, but each API must be enabled separately.
  2. Open APIs & Services → Library, find Google Search Console API, and enable it in that project.
  3. Open Google Auth Platform. If the app is not configured yet, choose Get started and complete its name, support email and contact details.
  4. Choose the appropriate audience. For a personal Google account, choose External. If the app remains in Testing, add the Google account you will use under Audience → Test users.
  5. Under Data Access → Add or remove scopes, add https://www.googleapis.com/auth/webmasters.readonly.
  6. Open Clients → Create client, select Desktop app, and create the client. Download its JSON when offered. Keep this original file; do not recreate it by copying values into a shell.

Google's Auth Platform introduction, OAuth client guide and scope configuration guide explain these screens.

Use the Google account that has access to your Search Console property when authorizing the app. External apps in Testing receive seven-day refresh tokens for this scope, so Testing is useful for initial setup but may require repeated authorization. Publishing status and Google's app-verification requirements are separate settings. Google OAuth expiry

In my initial setup, Google sign-in worked but listing properties returned 403 accessNotConfigured: the Search Console API had not been enabled. Authentication and API activation are separate steps.

Create a dedicated folder for this connection.

macOS:

mkdir -p "$HOME/.config/mcp-gsc"
chmod 700 "$HOME/.config/mcp-gsc"

Windows PowerShell:

$GscConfigDir = Join-Path $env:USERPROFILE '.config\mcp-gsc'
New-Item -ItemType Directory -Force -Path $GscConfigDir | Out-Null
Write-Output $GscConfigDir

Save the downloaded file inside that folder as oauth_client.json. On macOS, restrict its permissions:

chmod 600 "$HOME/.config/mcp-gsc/oauth_client.json"

Keep credentials and tokens in your user profile, outside a repository or shared folder. Unix chmod modes do not configure Windows access-control permissions.

3. Add the read-⁠only launcher

The upstream server requests the broader webmasters scope and exposes property and sitemap mutation tools. Google's narrower webmasters.readonly scope suits reporting. The following custom launcher selects it and removes the five mutation tools. This is a version-specific adaptation, not an upstream GSC_SCOPE setting. Google's scope definitions · Server source

Save the following as read_only_server.py in the same folder as oauth_client.json. Use a plain-text editor and UTF-8 encoding; ensure the filename does not end in .py.txt.

You can also download the same launcher and save it in that folder.

import os
import sys
from importlib.metadata import version
from pathlib import Path

if os.name == "posix":
    os.umask(0o077)

root = Path.home() / ".config" / "mcp-gsc"
root.mkdir(mode=0o700, parents=True, exist_ok=True)
if os.name == "posix":
    root.chmod(0o700)

os.environ["GSC_CONFIG_DIR"] = str(root)
os.environ["GSC_OAUTH_CLIENT_SECRETS_FILE"] = str(
    root / "oauth_client.json"
)
os.environ["GSC_ALLOW_DESTRUCTIVE"] = "false"
os.environ["GSC_DATA_STATE"] = "final"
os.environ["MCP_TRANSPORT"] = "stdio"

if version("mcp-search-console") != "0.4.1":
    raise RuntimeError("This launcher requires mcp-search-console==0.4.1")

import gsc_server

gsc_server.SCOPES = [
    "https://www.googleapis.com/auth/webmasters.readonly"
]
# This guide uses the explicitly configured OAuth account only.
gsc_server.get_gsc_service = gsc_server.get_gsc_service_oauth

for name in (
    "add_site", "delete_site", "submit_sitemap",
    "delete_sitemap", "manage_sitemaps",
):
    gsc_server.mcp.remove_tool(name)

# Upstream's static help text may advertise the removed mutation tools.
if hasattr(gsc_server, "get_capabilities"):
    gsc_server.mcp.remove_tool("get_capabilities")

if __name__ == "__main__":
    if "--login" in sys.argv:
        gsc_server.get_gsc_service()
        print("Credentials loaded. Next, verify property access and a report.")
    else:
        gsc_server.main()

The launcher also fixes the transport to local stdio and uses OAuth directly, preventing an inherited service-account fallback from selecting another account. It removes the upstream capability helper when present because its static help can still advertise tools removed by this configuration; normal MCP tool discovery remains available.

The package pin and uncaught removal errors are intentional: if the expected API changes, startup should fail visibly. Review the launcher before upgrading. Its default reports use finalized data; recent figures may appear later than in a dashboard showing fresh data.

Already connected with broader permissions?

Changing the requested scope does not revoke an existing authorization, and the server can reuse a cached token. Before treating an existing connection as read-only:

  1. Close the clients using this setup.
  2. Remove the relevant app's old grant from your Google Account connections.
  3. Delete this setup's cached token using the appropriate command below.
  4. Complete the sign-in step again, then verify actual property access.

macOS:

rm -f "$HOME/.config/mcp-gsc/token.json"

Windows PowerShell:

$GscToken = Join-Path $env:USERPROFILE '.config\mcp-gsc\token.json'
if (Test-Path -LiteralPath $GscToken) {
    Remove-Item -LiteralPath $GscToken
}

Revocation can invalidate the user's authorizations for other OAuth clients in the same Google Cloud project. If you reused your Analytics project, you may need to reconnect Analytics too. Google's token-revocation rules

4. Sign in and discover the exact Python path

Run the launcher with the interpreter inside its pipx environment. The commands discover pipx's location instead of assuming a default path. No virtual-environment activation is needed. pipx paths

macOS:

GSC_PYTHON="$(pipx environment --value PIPX_HOME)/venvs/mcp-search-console/bin/python"
GSC_LAUNCHER="$HOME/.config/mcp-gsc/read_only_server.py"
"$GSC_PYTHON" "$GSC_LAUNCHER" --login
printf '%s\n' "$GSC_PYTHON" "$GSC_LAUNCHER"

Windows PowerShell:

$GscPipxHome = (pipx environment --value PIPX_HOME).Trim()
$GscPython = Join-Path $GscPipxHome 'venvs\mcp-search-console\Scripts\python.exe'
$GscLauncher = Join-Path $env:USERPROFILE '.config\mcp-gsc\read_only_server.py'
& $GscPython $GscLauncher --login
Write-Output $GscPython
Write-Output $GscLauncher

Complete Google's browser sign-in and approve the read permission. The token is stored beside the launcher as token.json. Keep the printed Python and launcher paths. The message confirms that credentials were loaded; the report check below confirms they can read your property.

5. Connect your chosen client

You only need one of these client configurations. Keep the same terminal open for the CLI examples so the path variables remain defined. If you open a new terminal, repeat the variable assignments from step 4.

Codex

macOS:

codex mcp add google-search-console -- "$GSC_PYTHON" "$GSC_LAUNCHER"

Windows PowerShell:

codex mcp add google-search-console -- $GscPython $GscLauncher

This adds the connection to user-level Codex configuration, making it available across local projects. Repository-specific settings and managed policies can still affect availability. Codex MCP configuration

Claude Code

macOS:

claude mcp add --scope user --transport stdio google-search-console -- "$GSC_PYTHON" "$GSC_LAUNCHER"

Windows PowerShell:

claude mcp add --scope user --transport stdio google-search-console -- $GscPython $GscLauncher

--scope user makes the entry available across projects for your user account. In Claude Code, /mcp shows the server status. Claude Code MCP scopes

Claude Desktop

Open Claude Desktop once, then use its developer settings to open the configuration file, or locate it here:

SystemConfiguration file
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json

Merge the google-search-console entry into the existing mcpServers object. Preserve other settings and servers. Replace the sample paths with the exact paths from step 4; do not put shell variables such as $HOME or %USERPROFILE% inside these JSON values.

macOS example:

{
  "mcpServers": {
    "google-search-console": {
      "command": "/ABSOLUTE/PATH/TO/PIPX_PYTHON",
      "args": [
        "/Users/YOUR_NAME/.config/mcp-gsc/read_only_server.py"
      ]
    }
  }
}

Windows example: use forward slashes in JSON paths, or escape every backslash as \\.

{
  "mcpServers": {
    "google-search-console": {
      "command": "C:/FULL/PATH/TO/pipx/venvs/mcp-search-console/Scripts/python.exe",
      "args": [
        "C:/Users/YOUR_NAME/.config/mcp-gsc/read_only_server.py"
      ]
    }
  }
}

Save as UTF-8 JSON. Fully quit and reopen the app after editing its configuration. For CLI clients, start a new session. Claude Desktop configuration paths

6. Verify the connection, then ask a useful question

First ask:

Use the Google Search Console MCP server to list the properties I can access. Show each exact property identifier and my access level.

Choose an identifier from the response. sc-domain:example.com and https://example.com/ are different properties; retain the exact spelling and trailing slash returned by Google.

Then verify a small report:

For this property, use get_advanced_search_analytics with data_state="final" to retrieve the top ten queries for a complete 28-day period. Show the exact start and end dates, clicks, impressions, CTR and average position. State the latest date with returned data and any limitations. Do not invent missing values.

For a more useful follow-up:

Compare two consecutive complete 28-day periods using finalized data. Show the exact periods and identify pages whose clicks fell. For each candidate, examine query, impression and position changes. Separate what the data shows from possible explanations, and suggest one next check per page.

The advanced tool accepts explicit dates and pagination. Google's API returns top rows and does not guarantee every query; filtered or limited rows should not be presented as whole-site totals. Recent data can also be incomplete. Search Analytics API reference

Common setup problems

If the server reports as connected but Claude Code shows no tools, check what the server exposes, active permission rules and on-demand discovery in this MCP tool-discovery answer.

SymptomWhat to check
403 accessNotConfiguredEnable Google Search Console API in the OAuth client's project. Allow a little time for a new activation to propagate.
No properties, or a permission errorCheck the Google account, property access and exact property identifier before retrying.
pipx is not recognized on WindowsRun py -3.13 -m pipx ensurepath, then fully reopen PowerShell.
py -3.13 is not recognized or finds no runtimeCheck the Python installation and launcher. Use the official Windows installer if necessary.
Python cannot find gsc_serverUse the pipx environment's Python path from step 4, not a different system interpreter.
Tool-removal or version error at startupConfirm mcp-search-console==0.4.1 is installed and the launcher was copied completely. Do not ignore failures in the required tool-removal block.
Works in one repository onlyCheck Claude Code's user scope or Codex's user configuration, plus any project override.
Login stops working after seven daysCheck whether the external OAuth app remains in Testing. Reauthorize after resolving its intended configuration. See why a Google OAuth connection can stop working after seven days.
Green MCP status, but reports failTest property listing and a report. Process startup is not proof of Google API permission.

Is a local MCP completely private or unlimited?

Local means the MCP process runs on your computer. It still calls Google's API, and report data returned to a cloud assistant is processed by that assistant's provider under your account's settings and terms. Your Google credentials should stay in the local credential files; do not paste them into chat or commit them to Git.

The API also has usage limits. URL Inspection currently has a per-property quota of 2,000 requests per day, so inspect targeted batches rather than treating the connection as an unlimited crawler. Search Console API limits

This stdio setup is for a client running locally. Adding it to your computer does not by itself make it available inside a browser-only ChatGPT or Claude conversation, or create an unattended hosted service.

Does connecting GSC improve rankings?

The connection makes your existing data easier to work with. The next step is still an editorial or technical decision: investigate a decline, improve a page that does not answer its query well, or fix an indexing problem. Use the report to choose that next action, then measure what changes.

For the other half of the picture—tracked behavior after a visit—continue with the Google Analytics MCP setup guide. This short answer explains why Search Console clicks and GA4 sessions differ.

Turning search visits into useful next steps?

Useful content needs a clear website behind it. I can help improve page structure, performance and the path from an article to your services, products or enquiry form.

See how I build and improve business websites⁠

Written by Henry Lõiv

Related guides

  1. How to use Search Console and GA4 with AI to choose website improvements Use Search Console and GA4 through MCP to choose website improvements. A worked fictional example, priority worksheet and prompts for checking the results. GuideSEO & AI Search 4 min read

Keep reading

All articles⁠
  1. Best AI agents in 2026: Grok Bot vs Dots and EU availability Compare AI agents by the work they can handle and whether you can use them in Estonia or the EU. Artificial Intelligence 5 min read
  2. AI Agent, Chatbot or Automation: What Does Your Business Need? A chatbot is an interface; an agent is one way to handle the work behind it. Follow a fictional customer enquiry to choose a practical system for your business. Artificial Intelligence 8 min read
  3. Claude Code vs Codex for Frontend Development: A Practical Comparison A documentation-based comparison with a runnable frontend exercise and a blank scorecard. No measured winner is claimed. Artificial Intelligence 9 min read

Hi!

I really love the sea, yachts, sunsets and starry skies.

Through this little 3D world, I can share a small part of myself with you.

Thank you for opening this bottle and reading my letter.

Henry

Let’s talk about your project

Tell me about your project

Tell me what you’d like to build or improve. You don’t need a finished brief — we’ll work out the scope and next steps together.

01 How can I help?
02 How many pages do you need?
03 Which extras do you need? Choose all that apply
04 When does it need to be ready?
05 Project details
06 Your contact details

Enquiry received

Thank you!

Your enquiry has been received. I usually reply by email within 2 working days.