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.
| Question | Data 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
- Create or select a project. You may reuse the Analytics project's credentials infrastructure, but each API must be enabled separately.
- Open APIs & Services → Library, find Google Search Console API, and enable it in that project.
- Open Google Auth Platform. If the app is not configured yet, choose Get started and complete its name, support email and contact details.
- 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.
- Under Data Access → Add or remove scopes, add
https://www.googleapis.com/auth/webmasters.readonly. - 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:
- Close the clients using this setup.
- Remove the relevant app's old grant from your Google Account connections.
- Delete this setup's cached token using the appropriate command below.
- 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:
| System | Configuration 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.
| Symptom | What to check |
|---|---|
403 accessNotConfigured | Enable 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 error | Check the Google account, property access and exact property identifier before retrying. |
pipx is not recognized on Windows | Run py -3.13 -m pipx ensurepath, then fully reopen PowerShell. |
py -3.13 is not recognized or finds no runtime | Check the Python installation and launcher. Use the official Windows installer if necessary. |
Python cannot find gsc_server | Use the pipx environment's Python path from step 4, not a different system interpreter. |
| Tool-removal or version error at startup | Confirm 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 only | Check Claude Code's user scope or Codex's user configuration, plus any project override. |
| Login stops working after seven days | Check 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 fail | Test 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.