GSC SEO MCP

Professional Google Search Console MCP server for SEO people who want real search data inside Cursor, Claude Code, Claude Desktop, Gemini CLI, and any MCP-compatible client.

Instead of only wrapping raw API calls, this server gives your AI assistant a full SEO operator console: performance snapshots, quick-win keywords, content decay, CTR opportunities, cannibalization, brand vs non-brand, search intent, internal linking ideas, URL inspection, sitemap management, Indexing API notifications, multi-site dashboards, and Markdown reports.

Why SEOs Will Like It

• 40 MCP tools built around Search Console workflows, not generic data dumps.

• Works in Cursor, Claude Code, Claude Desktop, Gemini CLI, and other stdio MCP clients.

• Supports service accounts for agencies and OAuth for personal accounts.

• Uses Search Analytics, URL Inspection, Sites, Sitemaps, and optional Indexing API support.

• Returns provenance with date ranges, filters, dimensions, row counts, and data state.

• Includes a verify_claim tool so the assistant can re-check important numbers before client reporting.

• Generates Markdown reports you can use as a starting point for audits, retainers, and stakeholder updates.

Related MCP server: mcp-seo-audit

What You Can Ask

Show me the biggest SEO opportunities for sc-domain:example.com.
Which pages are losing clicks and why?
Find high-impression keywords ranking positions 4 to 15.
Split branded vs non-branded search performance for the last 90 days.
Which pages have CTR below expected for their position?
Find internal link opportunities from strong pages to weaker pages.
Inspect these URLs and summarize canonical/indexing problems.
Generate a Markdown GSC report for the last 28 days.
Verify the claim that organic clicks increased 18% this month.

Tool Catalog

Core And Setup

Search Analytics

SEO Analysis

Indexing, Sitemaps, And URLs

Reporting And Safety

Use It

Users do not need to clone this repo, install dependencies, or run npm run build.

After the developer publishes this package to npm, users add it to any MCP client with:

npx -y gsc-seo-mcp

The MCP client runs the server as a local stdio process. Users do not deploy the server; they only configure their MCP client to run the published npm package.

Requirements:

• Node.js 20 or newer.

• A Google Cloud project with the Search Console API enabled.

• Search Console property access for the Google user or service account.

• Optional: Indexing API enabled if you want to use indexing_* tools.

For Maintainers: Publish To npm

As the developer, publish this package to npm. Users will not deploy it themselves.

This is a stdio MCP server, so it is not meant to be deployed like a normal web app on Vercel, Render, or a VPS. The user's MCP client starts the already-published package locally with npx, then passes credentials through the MCP config.

Maintainer release flow:

1. Push the source code to GitHub.

2. Publish the package to npm as gsc-seo-mcp.

3. Tell users to add npx -y gsc-seo-mcp to Cursor, Claude, or Gemini.

Why npm is best:

• No user build step.

• No manual dist/index.js path.

• Works across Windows, macOS, and Linux.

• Users keep their Google credentials on their own machine.

• Updates are easy: publish a new npm version, users automatically get it through npx.

Hosted remote MCP is possible later, but it needs an HTTP/SSE transport, proper multi-user OAuth, token storage, encryption, and account isolation. For a public SEO tool, npm is the safer and cleaner first release.

Google Setup

You do not need a separate .env file to use this MCP server. Put the values in your MCP client config under the server's env block, as shown in the Cursor, Claude, and Gemini examples below.

The .env.example file is only a copy/paste reference for developers.

There are two good ways to connect Google Search Console:

If you are not sure, start with Service Account. It is the cleanest path for MCP clients because the MCP can start quietly in the background.

Step 1: Create a Google Cloud Project

Google APIs are enabled inside a Google Cloud project. This project is just a container for API access; it is not your website and it is not your Search Console property.

1. Open Google Cloud Console: https://console.cloud.google.com/

2. Click the project selector at the top of the page.

3. Click New Project.

4. Name it something clear, for example GSC SEO MCP.

5. Click Create.

6. After Google creates it, make sure this project is selected in the top project selector.

Step 2: Enable the Required APIs

1. In Google Cloud Console, go to APIs & Services -> Library.

2. Search for Google Search Console API.

3. Open it and click Enable.

4. Optional: search for Indexing API and enable it only if you need the indexing_* tools.

The Indexing API is only for eligible JobPosting and livestream BroadcastEvent pages. It is not a general "force Google to index my page" API.

If you prefer Google Cloud CLI:

gcloud services enable searchconsole.googleapis.com
gcloud services enable indexing.googleapis.com

Option A: Service Account Setup

Use this if you want the easiest MCP setup for clients or team members.

1. Create the service account

1. In Google Cloud Console, go to IAM & Admin -> Service Accounts.

2. Click Create service account.

3. Service account name: gsc-seo-mcp.

4. Click Create and continue.

5. For project roles, you can usually skip role assignment and click Continue.

6. Click Done.

7. Copy the service account email. It looks like this:

gsc-seo-mcp@your-project-id.iam.gserviceaccount.com

Cloud IAM roles do not give this account access to your Search Console data. Search Console access is granted separately in Search Console itself.

2. Download the service account JSON file

1. Open IAM & Admin -> Service Accounts.

2. Click the service account you just created.

3. Open the Keys tab.

4. Click Add key -> Create new key.

5. Choose JSON.

6. Click Create.

7. Google downloads a .json file to your computer.

Save it somewhere stable, for example:

macOS/Linux: /Users/your-name/keys/gsc-seo-mcp.json
Windows: C:/Users/your-name/keys/gsc-seo-mcp.json

Do not commit this file to GitHub. Treat it like a password.

3. Add the service account to Search Console

1. Open Google Search Console: https://search.google.com/search-console

2. Select the property you want the MCP to access.

3. Go to Settings -> Users and permissions.

4. Click Add user.

5. Paste the service account email.

6. Choose a permission level:

   • Full: recommended if you want all tools, including sitemap submit/delete.

   • Restricted: okay for read-only reporting in many cases.

7. Click Add.

You must be a property owner to add users in Search Console.

4. Use this MCP config

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "service_account",
        "GSC_KEY_FILE": "/absolute/path/to/gsc-seo-mcp.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

For Windows paths, either use forward slashes:

"GSC_KEY_FILE": "C:/Users/your-name/keys/gsc-seo-mcp.json"

Or escape backslashes:

"GSC_KEY_FILE": "C:\\Users\\your-name\\keys\\gsc-seo-mcp.json"

Option B: OAuth Desktop Setup

Use this if you want each user to sign in with their own Google account.

With OAuth, you do not manually create a token file. You download a client secret JSON file from Google Cloud. The first time the MCP runs, it opens a browser, the user signs into Google, and the MCP saves a local token file automatically.

1. Configure the Google Auth consent screen

Google may call this area Google Auth Platform or OAuth consent screen, depending on the Cloud Console UI.

1. In Google Cloud Console, go to APIs & Services -> OAuth consent screen or Google Auth Platform -> Branding/Audience.

2. Choose the user type:

   • Internal if you are inside a Google Workspace organization and only your organization will use it.

   • External if you are using a normal Gmail account or users outside your organization.

3. Add an app name, for example GSC SEO MCP.

4. Add your support email.

5. Add your developer contact email.

6. Save the app.

7. If the app is in testing mode, add your Google account under Test users.

For personal use, testing mode is fine. Users may see an "unverified app" warning because this is your own local OAuth app.

2. Create the OAuth client ID

1. Go to APIs & Services -> Credentials.

2. Click Create credentials -> OAuth client ID.

3. For application type, choose Desktop app.

4. Name it GSC SEO MCP Desktop.

5. Click Create.

6. Click Download JSON.

The downloaded file is often named something like:

client_secret_1234567890-abc.apps.googleusercontent.com.json

Save it somewhere stable, for example:

macOS/Linux: /Users/your-name/keys/gsc-oauth-client.json
Windows: C:/Users/your-name/keys/gsc-oauth-client.json

Do not commit this file to GitHub.

3. Use this MCP config

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "oauth",
        "GSC_OAUTH_SECRETS_FILE": "/absolute/path/to/gsc-oauth-client.json",
        "GSC_TOKEN_FILE": "/absolute/path/to/gsc-oauth-token.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

The GSC_TOKEN_FILE path is where the MCP will save the generated OAuth token after the browser login finishes. If you omit it, the default is:

~/.gsc-seo-mcp/token.json

4. First run

1. Restart your MCP client.

2. Ask the assistant to run server_health or list_properties.

3. Your browser opens a Google login screen.

4. Sign in with the Google account that has Search Console access.

5. Approve the requested access.

6. Return to your MCP client and try list_properties again.

If Google shows an "unverified app" warning for your own OAuth app, open Advanced and continue. Only do this for an OAuth app you created yourself or one you trust.

Which JSON File Is Which?

Search Console Property Format

Use the exact property format from Search Console:

sc-domain:example.com
https://www.example.com/

Domain properties use sc-domain:. URL-prefix properties usually need the protocol and trailing slash.

MCP Config Variables

Client Setup

Use absolute paths for credential files. The MCP package itself can run through npx, so users do not need a local project path.

Cursor

Create .cursor/mcp.json in your project or configure it globally:

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "service_account",
        "GSC_KEY_FILE": "/absolute/path/to/service-account.json",
        "GSC_SITE_URL": "sc-domain:example.com",
        "GSC_BRAND_TERMS": "example,example brand"
      }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json.

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "service_account",
        "GSC_KEY_FILE": "/absolute/path/to/service-account.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

Project config option, create .mcp.json:

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "service_account",
        "GSC_KEY_FILE": "/absolute/path/to/service-account.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

CLI option:

claude mcp add --transport stdio \
  --env GSC_AUTH_MODE=service_account \
  --env GSC_KEY_FILE=/absolute/path/to/service-account.json \
  --env GSC_SITE_URL=sc-domain:example.com \
  gsc-seo -- npx -y gsc-seo-mcp

Then run:

claude mcp list

Gemini CLI

Gemini CLI reads MCP servers from settings.json.

User settings:

~/.gemini/settings.json

Project settings:

.gemini/settings.json

{
  "mcpServers": {
    "gsc-seo": {
      "command": "npx",
      "args": ["-y", "gsc-seo-mcp"],
      "env": {
        "GSC_AUTH_MODE": "service_account",
        "GSC_KEY_FILE": "/absolute/path/to/service-account.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      },
      "timeout": 120000,
      "trust": false
    }
  }
}

Example Workflows

Find quick wins

Use gsc-seo quick_wins for sc-domain:example.com over the last 90 days.
Focus on queries with at least 500 impressions and positions 4 to 12.

Diagnose a traffic drop

Use traffic_drop_diagnosis for the last 28 days compared with the previous 28 days.
Group by page and explain whether losses are ranking, CTR, demand, or mixed.

Prepare a page refresh

Use query_page_fit and title_meta_brief for https://www.example.com/blog/my-post/.
Turn the query data into a content refresh brief.

Verify reporting numbers

Before you tell the client clicks increased by 18%, run verify_claim for the exact date range.

Data Accuracy Notes

• Search Analytics rows are sorted by clicks and may not include every possible row because the Search Console API has internal limits.

• GSC_DATA_STATE=all includes fresh data when available. Use final when you need finalized reporting.

• URL Inspection shows the status of the version in Google's index. It is not a live URL test.

• Indexing API tools are included for eligible JobPosting and BroadcastEvent pages. Google does not position the Indexing API as a general-purpose indexing shortcut.

Security Notes

• Never commit service account keys, OAuth client secrets, or token files.

• Use least-privilege Search Console permissions where possible.

• Review tool calls before approving write actions such as delete_site, delete_sitemap, submit_sitemap, and indexing_publish_url.

• Keep generated reports out of public repos if they contain private client performance data.

Development

npm install
npm run check
npm run build
npm run dev

The server uses stdio. Do not print normal logs to stdout because stdout is reserved for MCP protocol messages.

Maintainer Release

Only maintainers need to build. Users should use npx -y gsc-seo-mcp.

Publish to npm:

npm login
npm version patch
npm publish
git push --follow-tags

prepublishOnly runs npm run check and npm run build automatically before publishing, so the npm package includes the compiled dist folder.

Troubleshooting

The MCP client cannot see tools

Make sure Node.js 20+ is installed, the package name is correct, and the MCP config uses:

npx -y gsc-seo-mcp

Also verify that every credential path in your MCP config is absolute.

Service account has no properties

Add the service account email to the Search Console property under Settings -> Users and permissions.

URL Inspection fails

Make sure inspectionUrl belongs to the property in siteUrl. For URL-prefix properties, use the exact prefix property including protocol and trailing slash.

OAuth does not open the browser

Set GSC_OAUTH_PORT=0 to let the server choose a free local port. If your environment blocks browser launching, run the server locally on your own machine instead of a remote shell.

Roadmap

• Remote HTTP transport for hosted team deployments.

• Saved report templates for technical SEO, content SEO, and executive summaries.

• Optional Looker Studio/BigQuery export helpers.

• MCP prompts for common agency workflows.

• Rich resources for reusable saved audits.

Official References

• Create Google Cloud projects

• Enable Google APIs

• Create OAuth and service account credentials

• Create service account keys

• Search Console users and permissions

• Search Analytics query

• URL Inspection API

• Sitemaps API

• Sites API

• Indexing API

• Model Context Protocol

License

MIT

If this helps your SEO workflow, star the repo so more SEOs can find it.