GSC SEO MCP

Connect Google Search Console to Cursor, Claude, or Gemini. Ask questions in plain English and get real SEO data back.

What you can ask your AI once it's set up

Show me the biggest SEO opportunities for my site.
Which pages are losing clicks?
Find keywords ranking positions 4–15 that I can push to page 1.
Split branded vs non-branded traffic for the last 90 days.
Which pages have bad CTR for their ranking position?
Inspect these URLs and tell me what's wrong with indexing.
Generate a Markdown SEO report for the last 28 days.

Related MCP server: mcp-gsc-advanced

Setup

There are two parts:

1. Google — give the MCP access to your Search Console data

2. Your AI app — tell Cursor / Claude / Gemini how to run it

Pick your Google auth method first:

Part 1 — Google Setup

Step 1: Create a Google Cloud project

This is just a container for API access. It is not your website.

1. Go to console.cloud.google.com

2. Click the project dropdown at the top → New Project

3. Name it GSC SEO MCP and click Create

4. Make sure it's selected in the top dropdown after creation

Step 2: Enable the Search Console API

1. Go to APIs & Services → Library

2. Search Google Search Console API → click it → click Enable

3. Optional: also enable Indexing API if you want the indexing_* tools (only useful for JobPosting/livestream pages)

Option A: Service Account (recommended)

1. Create the service account

1. Go to IAM & Admin → Service Accounts

2. Click Create service account

3. Name: gsc-seo-mcp → click Create and continue

4. Skip the role assignment → click Continue → click Done

5. Copy the service account email — looks like:

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

2. Download the key file

1. Click the service account you just created

2. Go to the Keys tab → Add key → Create new key → JSON → Create

3. Google downloads a .json file — save it somewhere safe, like:

   • Mac/Linux: /Users/your-name/keys/gsc-seo-mcp.json

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

Don't commit this file to GitHub. Treat it like a password.

3. Add it to Search Console

1. Open search.google.com/search-console

2. Select your property

3. Go to Settings → Users and permissions → Add user

4. Paste the service account email, set permission to Full, click Add

You need to be a property owner to do this.

4. Your 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"
      }
    }
  }
}

Windows path tip — use forward slashes or double backslashes:

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

Option B: OAuth (sign in with Google)

Use this if you want to connect with your own Google account via browser login.

1. Set up the OAuth consent screen

1. Go to APIs & Services → OAuth consent screen

2. Choose External (works for Gmail accounts) → fill in app name, email → save

3. If the app is in testing mode, add your Gmail under Test users

2. Create the OAuth client

1. Go to APIs & Services → Credentials → Create credentials → OAuth client ID

2. Application type: Desktop app → name it GSC SEO MCP Desktop → click Create

3. Click Download JSON — save it like:

   • Mac/Linux: /Users/your-name/keys/gsc-oauth-client.json

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

3. Your 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"
      }
    }
  }
}

GSC_TOKEN_FILE is where the MCP saves your login token after the first browser sign-in. If you leave it out, it saves to ~/.gsc-seo-mcp/token.json by default.

4. First run

Restart your MCP client, then ask it to run server_health or list_properties. A browser window will open — sign in with Google and approve access. That's it, no repeat login needed.

If Google shows an "unverified app" warning, click Advanced → Continue — this is your own OAuth app, it's fine.

Part 2 — Add to your AI app

Node.js 20+ is required. Download here if you don't have it.

Cursor

Create .cursor/mcp.json in your project folder (or use global MCP settings):

{
  "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": "mybrand,mybrand.com"
      }
    }
  }
}

Claude Desktop

Edit claude_desktop_config.json:

• Mac: ~/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

Create .mcp.json in your project:

{
  "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"
      }
    }
  }
}

Or via CLI:

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

Gemini CLI

Edit ~/.gemini/settings.json (or .gemini/settings.json in your project):

{
  "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
    }
  }
}

Property URL format

Use the exact format from Search Console:

sc-domain:example.com        ← domain property (recommended)
https://www.example.com/     ← URL-prefix property (include the trailing slash)

All config variables

Tools

Core

Search Analytics

SEO Analysis

Indexing, Sitemaps, URLs

Reporting

Troubleshooting

Tools don't show up in my AI app Make sure Node.js 20+ is installed. Check your MCP config uses npx -y gsc-seo-mcp exactly. All file paths must be absolute (not ~/ or relative).

Service account shows no properties You need to add the service account email to Search Console under Settings → Users and permissions.

URL Inspection fails The URL must belong to the property in GSC_SITE_URL. For URL-prefix properties, use the exact prefix with protocol and trailing slash.

OAuth doesn't open the browser Set GSC_OAUTH_PORT=0 to let it pick a free port. If you're on a remote machine, you'll need to run this locally instead.

Data notes

• Search Analytics rows are sorted by clicks. The API has internal row limits, so not every possible row is included.

• GSC_DATA_STATE=all includes fresh data. Use final for finalized reporting numbers.

• URL Inspection shows Google's index state, not a live crawl.

• The Indexing API is for JobPosting and BroadcastEvent pages only — it's not a general indexing shortcut.

Security

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

• Use read-only Search Console permissions if you don't need write tools.

• Review delete_site, delete_sitemap, submit_sitemap, and indexing_publish_url calls before approving them.

Official docs

• Create a Google Cloud project

• Enable APIs

• Create credentials

• Search Console users and permissions

• Search Analytics API

• URL Inspection API

• Indexing API

• Model Context Protocol

License

MIT. If this saves you time, star the repo.