Yes. Refresh Agent uses read-only OAuth access. Claude Code can analyse your performance data but cannot change settings, pages, campaigns, or any data in your Google account.

Google Search Console MCP for Claude Code

Q: What does the free tier include?

The free tier includes a limited number of data requests each month. Enough to test the connection and validate the workflow. Upgrade to the $10/month Live Data plan for unlimited requests.

Q: Do I need to understand MCP?

No. Your part is one npx command in the terminal and one Google sign-in. The MCP bridge runs on our end. Claude Code handles the rest.

What Is Google Search Console MCP for Claude Code?

Google Search Console MCP for Claude Code is a managed data bridge that gives Claude Code, Codex, and other AI agents live access to your Google Search Console data through MCP — without any Google Cloud Platform setup.

Instead of creating a GCP project, configuring OAuth consent screens, generating JSON key files, and managing refresh tokens, you connect once with a single Google sign-in. Your agent can then query your live search data directly. This page covers the google search console mcp workflow end-to-end.

The Google Cloud Problem

Most marketers are still downloading CSV files, copying data between tabs, and pasting into ChatGPT. Their AI is blind to their actual numbers.

Connecting Claude Code to Google Search Console the normal way means opening Google Cloud Platform. GCP was built by engineers for other engineers. OAuth consent screens, service accounts, JSON key files, environment variables — thirty minutes of clicking through warnings before you even make your first request. And when you finally hit enter: Invalid authentication token. Quota exceeded. Your morning is gone.

If you run an agency it gets worse. You do not own the client's Google account. You cannot generate API keys. You email the client asking them to create a service account and give you owner permissions. They forward it to their IT guy. He says no. The project stalls before it starts.

Connect in 30 Seconds

I built a bridge that skips all of it. One command, one Google sign-in, and Claude has live data.

npx skills add marketingskills/seo/skills/live-search-console-data

Open Claude Code. Ask it: "analyse my seo performance". The skill shows a secure link. Click it. Log in with your normal Google account. The bridge is built instantly — read-only OAuth, no GCP project required.

Now Claude sees your live numbers. Which pages are losing traffic. Which keywords are on page 2 with high impressions. What to fix next.

How the MCP Bridge Works

When you ask Claude a question about your search traffic, here is exactly what happens under the hood:

Authentication check. Refresh Agent validates your stored OAuth token (read-only scopes for Search Console webmasters.readonly and analytics.readonly). If expired, it refreshes automatically via the stored refresh token — you never see a token error.
Tool selection. Claude decides which GSC tool matches your question. The bridge exposes tools for overview queries, drilled-down analytics with custom dimensions and filters, content gap analysis, URL inspection, cannibalization detection, keyword target validation, and index coverage checks. Each tool maps to specific Search Console API dimensions and caps its row limit (1,000 max) to protect the LLM context window.
API call. The selected tool calls the Google Search Console API (POST webmasters/v3/sites/{site}/searchAnalytics/query) with the appropriate dimensions, date range, and optional filters. The response includes clicks, impressions, CTR, and average position per dimension combination.
Optional sub-agent orchestration. For strategy questions, the bridge routes through a dedicated GSC research sub-agent. It calls gsc_overview for totals and top queries/pages, then summarize_gsc_content_gaps for high-impression/low-CTR opportunities, and optionally gsc_metric_filter for logic-based slices — all without flooding the context with raw rows.
Synthesis. Claude synthesizes the metrics into a natural language answer with the evidence inline. You get a diagnosis, not a spreadsheet.

Dimensions, Sampling, and Rate Limits

Available Dimensions

Dimension	GSC API Key	Common Use
`query`	`query`	Keyword performance, content gap analysis, cannibalization detection
`page`	`page`	Page-level traffic changes, URL-specific diagnosis
`country`	`country`	Geo-specific SEO performance (ISO country codes)
`device`	`device`	Mobile vs desktop vs tablet traffic comparison
`searchAppearance`	`searchAppearance`	AI Overviews, AMP, video, and rich result tracking
`date`	`date`	Time-series aggregation and trend analysis

Dimensions can be combined. For example, query + page returns per-keyword-per-URL rows used in cannibalization analysis. The gsc_metric_filter tool supports operators: EQUALS, CONTAINS, NOT_EQUALS, NOT_CONTAINS.

Data Sampling

Google samples Search Console data when the total row count exceeds certain thresholds. The exact threshold varies by property and is not publicly documented. The bridge passes Google's response as-is — if Google returns sampled data, that is what Claude sees. For most properties with under ~50,000 rows per query, Google typically returns unsampled data.

Rate Limits

Google enforces a daily API quota per property (approximately 10,000 requests per day per property). The bridge stays well within this limit. Refresh Agent adds a monthly request cap on the user side: 40 requests/month on the free tier. The $10/month Live Data plan removes this cap entirely (subject to Google's own quotas and your account permissions). When the monthly cap is hit, tools return a clear error with an upgrade link — no silent failures.

What Agents Can Do With It

The main use case is to pull clicks, impressions, CTR, positions, pages, and queries into an agent workflow. That makes the agent useful for live diagnosis instead of generic advice.

Investigate organic traffic or conversion changes with source data.
Turn page, query, channel, and conversion evidence into next steps.
Feed Google data into coding, content, SEO, and proposal workflows.

Example Prompts

Try these after connecting Google:

Which Search Console pages lost the most clicks in the last 28 days?

Analyse my SEO performance for the last 28 days

Which pages are losing traffic and what should I update?

Find keywords where I rank on page 2 with high impressions

Write this week's SEO performance brief

For related workflows, see Google Analytics MCP.

Free Tier and $10 Live Data Plan

Free for a limited number of requests each month. Upgrade to the $10/month Live Data plan for unlimited data requests, subject to Google's own API quotas and account permissions.

The free tier is for trying the connection and validating that your agent can read the data. The Live Data plan is for ongoing terminal use when you want Google data available every time you work.

Upgrade to $10/mo Unlimited

Frequently Asked Questions

Do I need to create a Google Cloud project to use this?

No. Refresh Agent handles the Google connection. You sign in with your normal Google account through a secure OAuth link. No GCP project, no service account, no JSON key file required.

Can I use this for client Search Console properties?

Yes. As long as your Google account has access to the client's Search Console property, even as a restricted user, you can connect through Refresh Agent. No admin rights needed.

Is my data safe?

Yes. Refresh Agent uses read-only OAuth access. Claude can analyze your performance data but cannot change settings, pages, or campaigns in your Google account.

What does the free tier include?

A limited number of data requests each month. Enough to test the connection and validate the workflow. Upgrade to the $10/month Live Data plan for unlimited requests.

Do I need to understand MCP?

No. Your part is one npx command in the terminal and one Google sign-in. The MCP bridge runs on our end. Claude Code handles the rest.