How to Use Google Search Console with Claude Code in 2026

Add the hosted SearchConsole.ai MCP server at the right Claude Code scope, complete OAuth, and use search evidence in a repository.

Automatable now Beginner

Connect SearchConsole.ai to Claude Code when you want an agent to analyze first-party search performance and then inspect the website code that produced it. Claude Code can compare clicks, impressions, CTR, and average position, investigate page-query relationships, inspect Google's indexed-version evidence, review sitemaps, and relate those findings to the repository open in your terminal.

SearchConsole.ai's Search Console operations are read-only. The connection cannot change Search Console or your website. Claude Code can still edit local files and run commands through its own permission system when you explicitly ask it to implement an evidence-backed improvement.

Quick setup: Sign up to SearchConsole.ai for free, then add the hosted server to Claude Code with the command below. You do not need to create a Google Cloud project or store Google credentials in the repository.

claude mcp add --transport http --scope user searchconsole-ai https://searchconsole.ai/mcp

After adding it, start Claude Code, run /mcp, select searchconsole-ai, and complete the browser authorization flow.

Before you connect

You need:

Claude Code installed and authenticated;
a Google account that can open at least one verified Search Console property;
a browser available for the MCP OAuth callback;
permission to add remote MCP servers if your organization manages Claude Code;
a local website repository if you want Claude to connect Search Console evidence to implementation.

Claude Code requires an eligible Claude subscription, organization seat, Console account, or supported cloud provider. Anthropic's installation documentation contains the current platform and account requirements.

Check that the command is available:

claude --version
claude mcp --help

If your installation is old enough that --transport http, --scope, or remote OAuth behaves differently, update it before continuing:

claude update

Native installations normally update automatically, while package-manager installations follow their package manager's update process.

Choose the correct MCP scope

Claude Code supports three MCP configuration scopes. The server is the same in each case; the scope controls where its configuration loads and whether the URL is shared with teammates.

Scope	Loads in	Shared with the team	Stored in	Best use
`local`	Current project	No	Project entry inside `~/.claude.json`	Private test or one sensitive repository
`project`	Current project	Yes	`.mcp.json` in the project root	Team-standard connection
`user`	Every local project	No	`~/.claude.json`	Personal SEO work across several sites

The default is local. This guide recommends user for an individual who wants Search Console available across repositories. Choose local when you want to minimize where the tools appear. Choose project only when the team deliberately wants the server URL checked into version control.

The OAuth credentials are personal. A project-scoped configuration shares the endpoint, not one person's Google access. Each teammate authorizes their own SearchConsole.ai connection and sees only the Search Console properties available to their Google account.

Step 1: add the remote MCP server

Run this command from a terminal:

claude mcp add --transport http --scope user searchconsole-ai https://searchconsole.ai/mcp

The order matters. Current Claude Code expects options such as --transport and --scope before the server name. The remaining values are:

http: the recommended transport for remote cloud services;
user: load the connection in every local project for this user;
searchconsole-ai: the local name Claude Code will show for the server;
https://searchconsole.ai/mcp: the hosted Streamable HTTP endpoint.

Do not add an authorization header, API key, Google token, client secret, or environment variable. SearchConsole.ai uses OAuth discovery and browser authentication.

Limit it to the current repository instead

For a private current-project connection:

claude mcp add --transport http --scope local searchconsole-ai https://searchconsole.ai/mcp

For a configuration the team can review and commit:

claude mcp add --transport http --scope project searchconsole-ai https://searchconsole.ai/mcp

The project form creates or updates .mcp.json with a configuration equivalent to:

{
  "mcpServers": {
    "searchconsole-ai": {
      "type": "http",
      "url": "https://searchconsole.ai/mcp"
    }
  }
}

Review that file before committing it. Claude Code asks users to approve project-scoped MCP servers from .mcp.json before loading them, because a project configuration can cause a client to connect to an external system.

Step 2: confirm the saved configuration

List the configured servers:

claude mcp list

Then inspect this server:

claude mcp get searchconsole-ai

Confirm that the type is HTTP, the URL is exactly https://searchconsole.ai/mcp, and the intended scope was selected. A trailing subpath, local URL, or copied authorization header is unnecessary.

If you previously created another searchconsole-ai entry, Claude Code resolves duplicate names by scope precedence: local, then project, then user. A stale local entry can therefore hide a correct user entry. Remove or rename the unintended definition instead of repeatedly adding duplicates.

Step 3: complete OAuth from the `/mcp` panel

Start Claude Code in a website repository:

cd /absolute/path/to/your/website
claude

Inside the interactive Claude Code session, run:

/mcp

Select searchconsole-ai and follow the authentication action. Claude Code recognizes that the remote server requires OAuth when it receives an authorization response, discovers the authorization metadata, and opens the sign-in flow in your browser.

The browser flow has two separate authorization boundaries:

Claude Code authorizes to the SearchConsole.ai MCP server.
SearchConsole.ai asks Google for access to your Search Console data.

Select the Google account that can open the required Search Console property. SearchConsole.ai requests Google's read-only scope:

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

It does not need the broader read/write webmasters scope. Claude Code stores its MCP OAuth tokens securely and refreshes them automatically; SearchConsole.ai separately manages the encrypted Google authorization. No token needs to be copied into .mcp.json, ~/.claude.json, CLAUDE.md, or a shell history.

Current Claude Code MCP documentation uses the interactive /mcp panel for remote OAuth. If older setup notes tell you to run claude mcp login, update Claude Code and use /mcp.

Step 4: verify the server and tool discovery

Open /mcp again after authorization. The server should show as connected and should report discovered tools.

Ask a deliberately narrow question first:

Use SearchConsole.ai to list every Google Search Console property I can access. Show the exact property identifier and permission level. Do not run an audit yet.

The response should use the MCP server rather than guessing from the repository's domain. Verify:

the expected property is present;
the Google account is the intended account;
the permission level is plausible;
Domain properties retain the sc-domain: prefix;
URL-prefix properties retain the complete URL and path prefix.

An OAuth connection does not create Search Console permissions. If a property is absent, open Search Console directly with the same Google account and confirm that it has access.

Step 5: run a repository-aware baseline

Begin with a stable comparison rather than an unrestricted audit:

Use SearchConsole.ai and the exact property identifier I select. Compare clicks, impressions, CTR, and average position for the last complete 28 days with the preceding 28 days. Exclude incomplete recent dates. Identify the largest page and query changes, and keep Google-reported evidence separate from hypotheses. Inspect this repository only when it helps test a hypothesis; do not edit files yet.

This prompt gives Claude three distinct evidence sources:

Search Console performance and indexing evidence through SearchConsole.ai.
The local repository's templates, metadata, internal links, structured data, redirects, and configuration.
Calculations and hypotheses Claude produces from the first two.

Ask Claude to label them separately. A ranking decline can coincide with a code change without proving that the change caused it.

Inspect a specific opportunity

After reviewing the baseline, narrow the task:

For the selected page, retrieve its leading queries and compare the last complete 28 days with the preceding period. Inspect the matching template, title logic, canonical, structured data, and internal links in this repository. Explain which findings are directly observed, which are calculated, and which remain hypotheses. Propose the smallest safe change with a validation plan.

Investigate indexing evidence

For a set of URLs:

Use SearchConsole.ai to inspect these URLs. Report Google's indexed-version status, last crawl, robots state, user-declared canonical, and Google-selected canonical. Then inspect the repository for code or configuration consistent with the returned evidence. Do not call the result a live URL test.

The URL Inspection API reports Google's indexed version. It does not run the live inspection available in the Search Console interface.

Control whether Claude can change the repository

Connecting SearchConsole.ai does not grant repository write access. Claude Code's own permission mode controls file edits and commands.

Anthropic's permission documentation describes these useful modes:

Plan mode reads and investigates without editing source files. Start here for an SEO audit.
Default mode prompts before edits and shell commands.
Accept Edits allows in-scope file edits with fewer prompts while retaining controls around other operations.

Start an audit in Plan mode when you want to approve the approach before implementation:

claude --permission-mode plan

Or press Shift+Tab during a session to cycle supported permission modes.

Once the evidence and proposed changes are correct, leave Plan mode and give an explicit implementation request:

Implement the approved, evidence-backed changes in this repository. Preserve existing behavior outside the affected pages, run the relevant tests, show the diff, and do not deploy, publish, or mutate an external service without asking me first.

SearchConsole.ai remains read-only throughout. Any file modification comes from Claude Code's Edit and shell capabilities and follows the current session's permissions.

Avoid bypassing permissions on an ordinary workstation. Anthropic recommends unrestricted modes only in isolated environments because they remove important protection against unintended commands and prompt injection.

Save a reproducible audit report

Do not leave the evidence only in a chat transcript. Ask Claude to create a dated report using the repository's documentation convention, for example:

docs/seo/search-console-audit-2026-07-20.md

The report should record:

the exact Search Console property;
stable and comparison date windows;
search type, dimensions, and filters;
observed metrics and affected pages or queries;
Search Console coverage and privacy limitations;
repository evidence inspected;
facts, calculations, and hypotheses;
files changed and tests run;
a validation window and success criteria.

For a public repository, do not commit confidential search queries, private URLs, customer names, or sensitive business performance. Save a redacted summary or keep the detailed report outside version control.

Continue with the full AI SEO audit guide for the evidence and prioritization workflow.

Use project scope only when everyone working in the repository should be offered the same MCP server:

claude mcp add --transport http --scope project searchconsole-ai https://searchconsole.ai/mcp

Commit only the generated .mcp.json. Do not commit OAuth tokens or copy one user's credentials into project settings. Each teammate:

pulls the project configuration;
reviews and approves the server;
opens /mcp;
authorizes their own SearchConsole.ai and Google account;
receives only their own Search Console property access.

Administrators can restrict MCP servers through managed configuration or URL allowlists. If Claude says enterprise MCP configuration has exclusive control, an administrator must add https://searchconsole.ai/mcp to the managed MCP configuration. Repeated local commands cannot override that policy.

Claude Code on the web

User- and local-scoped servers created on your workstation are stored in local configuration and do not automatically appear in Claude Code on the web. Anthropic's Claude Code on the web documentation instructs teams to declare required remote servers in the repository's .mcp.json instead.

Treat web execution as a separate environment. Confirm that the project configuration is available, the environment supports the required OAuth flow, and organizational policy permits the connection before expecting parity with the local CLI.

Use the connection in non-interactive workflows

Authenticate the MCP server in an interactive Claude Code session before relying on it in automation. OAuth servers cannot open an interactive login prompt during a headless claude -p run.

For scheduled or CI usage, determine whether the execution environment securely preserves the MCP authorization and has permission to access the intended Search Console property. Do not embed a user's Google access token or SearchConsole.ai token in a repository merely to make an unattended job work.

Begin recurring analysis with stable saved snapshots rather than a prompt that silently changes its date boundaries. The weekly Search Console audit guide explains how to preserve comparable windows and avoid overwriting history.

Understand the data boundary

The request path is:

Claude Code session and repository context
                 |
      selected MCP tool arguments
                 |
           SearchConsole.ai
                 |
       Search Console API result
                 |
      evidence returned to Claude Code

SearchConsole.ai receives the tool call inputs needed to fulfill a request, such as the property, dates, dimensions, filters, or URL. It does not automatically receive every file in the repository or the entire Claude Code conversation. Claude decides what relevant information to put into a tool call.

The reverse boundary matters too: Search Console output can contain query and URL text that Claude Code treats as external data. Do not tell the agent to follow instructions found inside page titles, query strings, or fetched content. Review proposed commands and changes before approval, particularly when the repository or external data is untrusted.

Review the SearchConsole.ai privacy policy, terms, and account deletion flow before connecting a sensitive property.

Troubleshoot the Claude Code connection

The add command reports an option or argument error

Confirm that every option appears before searchconsole-ai:

claude mcp add --transport http --scope user searchconsole-ai https://searchconsole.ai/mcp

Then run claude --version and claude update. Older Claude Code releases can have different remote MCP and OAuth behavior.

The server is saved but not authenticated

Start an interactive Claude Code session, run /mcp, select searchconsole-ai, and choose the authentication action. claude mcp list confirms configuration; it does not by itself complete the browser OAuth flow.

The browser does not open

Copy the authorization URL shown by Claude Code and open it manually. If Google authorization succeeds but the browser ends on a localhost callback error, copy the complete callback URL from the browser address bar and paste it into the URL prompt Claude Code displays.

The callback port is blocked

Firewalls, remote SSH sessions, containers, and port forwarding can interfere with Claude Code's localhost OAuth callback. First use the copy-and-paste callback fallback. A fixed callback port is normally needed only for servers that require a pre-registered redirect, not for SearchConsole.ai's dynamic registration flow.

The server connects but exposes no tools

Open /mcp and inspect its tool count. Confirm the endpoint is exactly https://searchconsole.ai/mcp and restart Claude Code after updating. Authentication and not-found errors require a configuration or authorization change and are not fixed by repeatedly retrying the same prompt.

Claude uses the wrong server definition

Run:

claude mcp get searchconsole-ai

Check local, project, and user scopes for duplicates. A local entry has higher precedence than project and user entries with the same name.

Enterprise policy blocks the server

Ask the Claude Code administrator whether managed MCP configuration, allowedMcpServers, or deniedMcpServers permits the SearchConsole.ai name and URL. Managed policy cannot be bypassed from a project file or user command.

The expected property is missing

Open Search Console with the same Google account and verify access. Clear the SearchConsole.ai authentication from /mcp, reconnect with the correct account, and list properties again. Preserve the exact sc-domain: or URL-prefix identifier returned by Google.

Claude does not use SearchConsole.ai for the prompt

Name the server explicitly and begin with property discovery. Keep the first request small. If tool search is enabled, Claude Code can load MCP tools on demand rather than placing every tool definition into the initial context.

Manage or remove the connection

Useful commands include:

claude mcp list
claude mcp get searchconsole-ai
claude mcp remove searchconsole-ai

Use Clear authentication for the server in /mcp when you want to revoke Claude Code's current MCP authorization and reconnect. Removing the configuration prevents the server from loading at that scope, but Google authorization is a separate layer.

For complete disconnection:

clear authentication in Claude Code's /mcp panel;
remove the MCP configuration from the intended scope;
revoke SearchConsole.ai from the Google Account if required;
use the SearchConsole.ai deletion flow if you want the service account and associated credentials removed.

Next step

Once Claude Code can list properties and run the stable 28-day comparison, use the AI SEO audit guide to turn the connection into an evidence-led repository workflow.

Connect SearchConsole.ai for free and give Claude Code read-only Search Console evidence without building and operating your own Google OAuth and remote MCP infrastructure.