Setup guide

Connect Google Search Console to Claude Code

Add the hosted CalmSEO MCP server to Claude Code with one command and sign in once. Claude Code can then read your Search Console clicks, queries, and pages while it works in your site's repo. Setup takes about five minutes.

Start setup free Full Claude docs

Before you start

What you need

A Google Search Console property you have access to. Owner, full, or restricted permission all work. Claude Code can only see properties the connected Google account can see.
Claude Code installed and signed in. Claude Code supports remote HTTP MCP servers with OAuth sign-in. See Anthropic's Claude Code MCP docs for the full command reference.
A free CalmSEO account. CalmSEO is the SEO MCP server that sits between Claude Code and Google. Claude Code calls CalmSEO tools, and CalmSEO reads from the Search Console API with a read-only token.
Your site's source code, ideally. The workflows below work best when page titles, meta descriptions, and copy live in the repo you open Claude Code in. If your content lives in a CMS, Claude Code can still draft the changes for you to paste in.

For Claude on the web or Claude Desktop, follow the Claude connector guide. This page covers the CLI only.

Steps

Set up Claude Code

Create a free CalmSEO account. Sign up at calmseo.com with your email address. Search Console tools are free on every plan and no card is needed.
Connect Google Search Console. In the CalmSEO dashboard, open the Google Search Console card and click Connect with Google. Approve the read-only scope on Google's consent screen using the account that can see your property.
Add CalmSEO to Claude Code. In your terminal, run claude mcp add --transport http calmseo https://mcp.calmseo.com/mcp. This registers the hosted CalmSEO MCP server under the name calmseo for the current project.
Authenticate with /mcp. Start claude in your project, run /mcp, select calmseo, and follow the prompt to authenticate. Your browser opens calmseo.com. Sign in if asked, then click Authorize on the MCP authorization page. The browser then redirects back to Claude Code to finish the sign-in.
Ask a first question. Ask Claude Code to use CalmSEO to list your Search Console properties. It calls list_gsc_sites and returns every property your Google account can see.

The command from step 3:

claude mcp add --transport http calmseo https://mcp.calmseo.com/mcp

If you prefer to sign in from the shell, run claude mcp login calmseo instead of using /mcp. Claude Code stores the token and refreshes it automatically, so you only sign in once per machine.

Scope

Choose where CalmSEO is available

Claude Code stores each MCP server in one of three scopes. The command above uses the default.

Local (default). Available only to you, and only in the project directory where you ran the command. Stored in ~/.claude.json.
User. Available to you in every project. Good if you work on several sites.
Project. Written to .mcp.json in the repo root so everyone who clones the repo gets the server.

To make CalmSEO available in every project:

claude mcp add --transport http --scope user calmseo https://mcp.calmseo.com/mcp

To share it with your team through the repo:

claude mcp add --transport http --scope project calmseo https://mcp.calmseo.com/mcp

That writes this entry to .mcp.json:

{
  "mcpServers": {
    "calmseo": {
      "type": "http",
      "url": "https://mcp.calmseo.com/mcp"
    }
  }
}

The file holds only the URL. Claude Code asks each teammate to approve project servers the first time, and each person signs in with their own CalmSEO account. They need Search Console connected in CalmSEO and access to the property in Google.

Verify

Check that it works

From your terminal, list the servers Claude Code knows about:

claude mcp list

You should see calmseo with its URL and connection status. Inside a session, /mcp shows the same status and lets you re-authenticate. Then run a first prompt:

Use CalmSEO to list my Search Console properties.

Domain properties look like sc-domain:example.com and URL-prefix properties look like https://www.example.com/. Use the exact ID in later prompts so Claude Code queries the right property.

Workflows

SEO workflows in your repo

Claude Code can read files, edit them, and run shell commands such as git log. With CalmSEO connected, it can pair Search Console data with the code that renders each page. Replace the example property and URLs with your own.

Improve a page that almost ranks

Queries at positions 5 to 30 already show the page in results, so updating that page is usually less work than writing a new one. Claude Code can pull those queries and open the file that renders the page in the same session.

Use CalmSEO to get the Search Console queries for https://example.com/pricing
over the last 28 days. Keep queries with an average position between 5 and 30
and at least 20 impressions. Then find the file in this repo that renders
/pricing and suggest title, meta description, and copy changes that cover them.

This uses get_gsc_page_queries, which is free. To see what currently ranks for the main query before editing, ask Claude Code to run search_serp, which uses 1 to 3 credits.

Find pages that lost clicks and check what changed

Claude Code can query two date ranges, rank pages by the drop, and then read the git history of the files behind those pages. The history shows what changed in the code during the same window. Treat the result as a list of places to check, since a code change and a traffic drop in the same window can be unrelated.

Use CalmSEO to compare clicks by page for sc-domain:example.com for the
last 28 days against the previous 28 days. List the ten pages with the
largest drop. For each one, find its source file and run git log on it
for the same period.

This runs query_gsc_search_analytics once per date range. Search Console data lags two to three days, so end the recent window three days ago for a fair comparison.

See which pages compete for the same query

When several pages get impressions for the same query, Search Console splits the data between them. Querying by query and page together shows the split, and Claude Code can then read each page to compare what they target.

Use CalmSEO to show every page that got impressions for queries containing
"pricing" in the last 90 days, with clicks, impressions, and position per page.
Then open the source file for each page and tell me whether they target
the same intent.

This uses query_gsc_search_analytics with the query and page dimensions and a contains filter.

Find routes with no search impressions

Claude Code can list the public routes in your repo and compare them with the pages Search Console reports. Routes with no impressions may be missing from the sitemap, blocked, or not indexed yet.

List the public routes in this repo. Then use CalmSEO to pull every page
with impressions for sc-domain:example.com over the last 90 days and tell me
which routes have none. Check whether those routes are in the sitemap this
repo generates, and list my submitted sitemaps with any errors.

This combines query_gsc_search_analytics with the page dimension and list_gsc_sitemaps. Search Console only reports pages that appeared in results, so treat each missing route as a lead to check in the Search Console URL Inspection tool.

More prompts for spotting pages worth updating are in finding SEO opportunities in Search Console.

Tools

Tools Claude Code gets

The six Search Console tools are free on every CalmSEO plan and do not use credits:

list_gsc_sites
query_gsc_search_analytics
get_gsc_top_queries
get_gsc_top_pages
get_gsc_page_queries
list_gsc_sitemaps

The same server also has third-party data tools that use credits:

search_serp: 1 to 3 credits depending on depth
audit_page: 5 credits
get_ranked_keywords: 5 to 20 credits depending on the result limit
get_keyword_search_volume: 15 credits per batch
find_keyword_ideas: 15 to 50 credits depending on the result limit

New accounts start with 20 credits. Paid plans start at $19 per month for 600 credits.

Permissions

Skip repeat approval prompts

Claude Code asks before it calls an MCP tool. To approve the free Search Console tools once, add them to the allow list in .claude/settings.json for one project or ~/.claude/settings.json for all projects:

{
  "permissions": {
    "allow": [
      "mcp__calmseo__list_gsc_sites",
      "mcp__calmseo__query_gsc_search_analytics",
      "mcp__calmseo__get_gsc_top_queries",
      "mcp__calmseo__get_gsc_top_pages",
      "mcp__calmseo__get_gsc_page_queries",
      "mcp__calmseo__list_gsc_sitemaps"
    ]
  }
}

Tools left off the list still prompt, so Claude Code checks with you before it runs a credit-based tool. The Claude Code permissions docs cover the rule syntax.

Troubleshooting

calmseo needs authentication or shows as failed. Run /mcp, select calmseo, and authenticate again. You can also run claude mcp login calmseo from the shell.
The browser does not open. Claude Code prints the sign-in URL. Copy it into your browser manually.
calmseo is missing in another project. The default local scope only covers the directory where you added it. Remove it with claude mcp remove calmseo and add it again with --scope user.
"Connect Google Search Console in the CalmSEO dashboard before using this tool." The MCP sign-in worked but your CalmSEO account has no Google connection yet. Complete step 2.
"That Google Search Console property is not connected to this CalmSEO account." The property ID does not match. Ask Claude Code to run list_gsc_sites and use the exact ID it returns. Domain and URL-prefix properties are separate properties with different data.
Claude Code warns that a tool result is large. Claude Code warns when MCP output passes 10,000 tokens and caps it at 25,000 tokens by default. Ask for fewer rows or a shorter date range, or raise the cap with the MAX_MCP_OUTPUT_TOKENS environment variable.
"No data" for recent dates. Search Console data arrives with a two to three day lag. Widen the date range.
Revoking access. Use Clear authentication in the /mcp menu, or run claude mcp remove calmseo, which also deletes the stored tokens. Click Disconnect in the CalmSEO dashboard to revoke the stored Google token.

FAQ

Frequently asked.

How do I connect Google Search Console to Claude Code?+

Create a free CalmSEO account and connect Google Search Console in the dashboard. Then run claude mcp add --transport http calmseo https://mcp.calmseo.com/mcp in your terminal, run /mcp inside Claude Code to sign in, and ask Claude Code to list your Search Console properties.

Is this free?+

Yes. Search Console tools are free on every CalmSEO plan with no card required. Credits only apply to third-party data such as keyword volume, SERP results, ranked keywords, and page audits. New accounts start with 20 free credits.

Is the connection read-only?+

Yes. CalmSEO requests only the read-only Search Console scope. Claude Code can read analytics, queries, pages, and sitemap status. It cannot submit URLs, edit properties, or change Search Console settings.

Should I use local, user, or project scope?+

Use local, the default, to try it in one repo. Use --scope user if you want CalmSEO in every project. Use --scope project to commit an .mcp.json entry so teammates get the server, each signing in with their own CalmSEO account.

I already added CalmSEO in claude.ai. Do I need to add it again?+

Not always. If you log in to Claude Code with a claude.ai account, connectors you added in claude.ai appear in /mcp automatically. Add it with claude mcp add if you log in with an API key or want a project-scoped entry. When both point at the same URL, the server added in Claude Code takes precedence.

Which Search Console tools does Claude Code get?+

Six tools: list_gsc_sites, get_gsc_top_queries, get_gsc_top_pages, get_gsc_page_queries, query_gsc_search_analytics, and list_gsc_sitemaps. Claude Code picks the right one based on your prompt.

Can I connect more than one Search Console property?+

Yes. You authorize one Google account and Claude Code can read every property that account has access to. Name the property in your prompt when you have several.

Is CalmSEO made by Anthropic?+

No. CalmSEO is an independent MCP server. It works with Claude Code because Claude Code supports the open MCP standard. We are not affiliated with or endorsed by Anthropic.

Keep reading

Connect Search Console to Claude Code

20 free credits + free Google Search Console tools. No card required.

Get started free