Google Search Console MCP Server

A Model Context Protocol (MCP) server that provides programmatic access to Google Search Console API data through Claude Code and Cursor.

Quick Start

New to this MCP server? Jump to Step-by-Step Setup Guide for complete instructions.

Features

• 🔍 List Sites - Get all Search Console properties you have access to
• 📊 Search Analytics - Query search performance data with flexible filtering
• 🗺️ Sitemap Information - Retrieve sitemap status and indexing statistics
• 🔎 URL Inspection - Check detailed indexing status of specific URLs
• 📤 Submit URL for Indexing - Request Google to index or remove URLs
• 📈 Compare Periods - Compare search performance between two time periods
• 🛡️ Robust Error Handling - Detailed error messages with actionable guidance
• 🔄 Automatic Retry Logic - Handles rate limits and transient failures
• ✅ Input Validation - Validates all parameters before API calls

Prerequisites

Before using this MCP server, you need:

1. Google Search Console

• Site registered in Search Console
• Site ownership verified
• Access to the Search Console property you want to query

2. Google Cloud Platform (GCP)

• A GCP project (free tier is sufficient)
• Google Search Console API enabled
• OAuth 2.0 Client ID credentials (Desktop app type)
• (Optional) Indexing API enabled if you want to use submit_url_for_indexing

💡 Note: You only need to set up GCP once. The CLIENT_ID and CLIENT_SECRET are reusable across multiple sites in your Search Console.

Setup

1. Configure Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "-p", "google-search-console-mcp-server", "google-search-console-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

⚠️ Important: The args must include all three parts:

1. "-y" - Auto-confirm npx prompt
2. "-p", "google-search-console-mcp-server" - Package name
3. "google-search-console-mcp" - Executable name (different from package name!)

💡 Note: GOOGLE_REDIRECT_URI defaults to http://localhost:8080 and doesn't need to be specified unless you want to use a different port.

2. Get Google OAuth Credentials

💡 Tip: You can use an existing OAuth 2.0 Client ID from other services (Supabase, Firebase, etc.) or create a new one.

1. Go to Google Cloud Console
2. Create or select a project
3. Enable APIs:
   • Navigate to "APIs & Services" → "Enable APIs and Services"
   • Search and enable "Google Search Console API"
   • (Optional) Enable "Indexing API" if you want to use submit_url_for_indexing
4. Create or use existing OAuth 2.0 Client ID:
   • Go to "APIs & Services" → "Credentials"
   • Option A: Use existing OAuth 2.0 Client (skip to step 5)
   • Option B: Create new → "OAuth 2.0 Client ID" → Application type: Desktop app
5. Configure Authorized redirect URIs:
   • Click on the OAuth 2.0 Client ID
   • Under "Authorized redirect URIs", click "Add URI"
   • Add: http://localhost:8080 (no trailing slash!)
   • Click "Save"
6. ⚠️ IMPORTANT: Add test users (if OAuth consent screen is in Testing mode):
   • Go to "OAuth consent screen"
   • Check the "Publishing status" - if it shows "Testing":
   • Scroll to "Test users" section
   • Click "+ ADD USERS"
   • Add your Google account email (the one you'll use to authenticate)
   • Click "Save"
   • Without this step, you'll get access_denied errors!

💾 Save your credentials: Copy the CLIENT_ID and CLIENT_SECRET. You'll need them in the next step.

3. Get Refresh Token

Run the interactive setup command:

npx -y -p google-search-console-mcp-server google-search-console-mcp-setup

You'll be prompted to enter:

• GOOGLE_CLIENT_ID (from step 2)
• GOOGLE_CLIENT_SECRET (from step 2)
• GOOGLE_REDIRECT_URI (press Enter for default: http://localhost:8080)

A browser window will open for authentication. After authorizing, the command will output the complete .mcp.json configuration with all three credentials including the GOOGLE_REFRESH_TOKEN.

Copy the configuration and paste it into your .mcp.json, then reload Claude Code window.

Usage

Once configured, you can use the tools in Claude Desktop or Claude Code:

Show me my Google Search Console sites

or

Get search performance data for example.com for the last 7 days

Available Tools

1. list_sites

Get all Search Console sites you have access to.

Parameters: None

Example:

Search Consoleのサイト一覧を教えて

2. get_analytics

Query search performance data for a specified date range.

Parameters:

• siteUrl (required): Site URL (e.g., "https://example.com/")
• startDate (required): Start date (YYYY-MM-DD)
• endDate (required): End date (YYYY-MM-DD)
• dimensions (optional): Array of dimensions ["query", "page", "country", "device", "searchAppearance"]
• rowLimit (optional): Max rows (default: 100, max: 25000)
• startRow (optional): Starting row for pagination

Example:

example.comの過去7日間のトップクエリを取得して

example.comの2025年1月1日から1月31日までの、
ページ別とデバイス別のパフォーマンスを500件取得して

3. get_sitemaps

Retrieve sitemap information for a site.

Parameters:

• siteUrl (required): Site URL

Example:

example.comのサイトマップ情報を確認して

4. inspect_url

Inspect the indexing status of a specific URL.

Parameters:

• siteUrl (required): Site URL (e.g., "https://example.com/")
• inspectionUrl (required): Full URL to inspect

Example:

https://example.com/blog/article のインデックス状態を検査して

5. submit_url_for_indexing

Submit a URL to Google for indexing or request URL removal using the Indexing API.

Parameters:

• url (required): Full URL to submit (e.g., "https://example.com/page")
• type (optional): Notification type - "URL_UPDATED" (default) or "URL_DELETED"

Example:

https://example.com/new-article をインデックスに送信して

https://example.com/old-page を削除申請して（type: URL_DELETED）

Note: Requires Indexing API to be enabled in Google Cloud Console and the https://www.googleapis.com/auth/indexing scope.

6. compare_periods

Compare search performance metrics between two time periods (e.g., this week vs last week).

Parameters:

• siteUrl (required): Site URL (e.g., "https://example.com/")
• currentStartDate (required): Current period start date (YYYY-MM-DD)
• currentEndDate (required): Current period end date (YYYY-MM-DD)
• previousStartDate (required): Previous period start date (YYYY-MM-DD)
• previousEndDate (required): Previous period end date (YYYY-MM-DD)
• dimensions (optional): Array of dimensions to group by
• rowLimit (optional): Max rows (default: 100, max: 25000)

Example:

Compare this week vs last week performance for example.com

Compare query performance for example.com between January 2025 and December 2024
(currentStartDate: 2025-01-01, currentEndDate: 2025-01-31,
 previousStartDate: 2024-12-01, previousEndDate: 2024-12-31,
 dimensions: ["query"])

API Limits

• Daily quota: 2,000 requests per project
• Per 100 seconds: 600 requests
• Data availability: Up to 16 months of historical data
• Data latency: Typically 2-3 days

Error Handling & Retry Logic

This MCP server includes comprehensive error handling:

Automatic Retries

• Rate Limiting (429): Automatically retries with exponential backoff
• Server Errors (5xx): Retries up to 3 times with increasing delays
• Transient Failures: Smart retry logic with jitter to prevent thundering herd

Input Validation

All tools validate inputs before making API calls:

• Site URL: Validates URL format and structure
• Dates: Validates YYYY-MM-DD format and logical date ranges
• Row Limits: Ensures limits are within API constraints (1-25,000)

Detailed Error Messages

Error messages include:

• Clear description of what went wrong
• HTTP status code
• Actionable steps to resolve the issue

Example:

Access denied for list sites (403)
Verify your authentication credentials and ensure you have access to this Search Console property.
You may need to add your account as a test user in Google Cloud Console.

Troubleshooting

Setup Issues

"invalid_client" Error During Authentication

Problem: When running the setup command, you get Error during authentication: invalid_client.

Causes & Solutions:

1. CLIENT_ID and CLIENT_SECRET mismatch

   • Verify they're from the same OAuth 2.0 Client in GCP Console
   • Copy them again directly from Google Cloud Console

2. Missing http://localhost:8080 in Authorized redirect URIs

   • If you're reusing OAuth credentials from other services (Supabase, Firebase, etc.)
   • Solution: Add http://localhost:8080 to "Authorized redirect URIs" in the OAuth 2.0 Client settings
   • You can have multiple redirect URIs (e.g., https://xxx.supabase.co/auth/v1/callback AND http://localhost:8080)

3. CLIENT_SECRET was regenerated

   • If you reset the secret in GCP Console, use the new one
   • Old secrets become invalid immediately

"could not determine executable to run" Error

Problem: npx google-search-console-mcp-server fails with "could not determine executable to run".

Solution: The package name and executable name are different. Use the correct .mcp.json configuration:

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "-p", "google-search-console-mcp-server", "google-search-console-mcp"],
      "env": { ... }
    }
  }
}

MCP Server Shows "✘ failed" in Claude Code

Debugging steps:

1. Check the error details:

   • In Claude Code's MCP status screen, press Enter on the failed server
   • Scroll down to see the stderr (error output)

2. Test manually:

   cd your-project-directory
   export GOOGLE_CLIENT_ID="your-id"
   export GOOGLE_CLIENT_SECRET="your-secret"
   export GOOGLE_REFRESH_TOKEN="your-token"
   npx -y google-search-console-mcp-server
   

3. Common causes:

   • Search Console API not enabled: Enable it in GCP Console
   • Wrong credentials: Verify CLIENT_ID, CLIENT_SECRET, and REFRESH_TOKEN
   • Expired token: Run the setup command again to get a new REFRESH_TOKEN
   • npx cache issue: Clear npx cache: rm -rf ~/.npm/_npx

4. Reload Claude Code: After fixing .mcp.json, reload the window (Ctrl/Cmd + Shift + P → "Developer: Reload Window")

Runtime Errors

"Missing required environment variables"

Make sure your .mcp.json file has all three environment variables: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REFRESH_TOKEN.

"redirect_uri_mismatch"

Ensure http://localhost:8080 (no trailing slash!) is added to Authorized redirect URIs in the OAuth 2.0 Client settings in Google Cloud Console.

"Error 403: access_denied"

1. ⚠️ Most common cause - OAuth consent screen is in Testing mode:
   • Go to "OAuth consent screen" in GCP Console
   • If "Publishing status" shows "Testing", you MUST add your email to "Test users"
   • Click "+ ADD USERS" in the "Test users" section
   • Add your Google account email (the one you're authenticating with)
   • Click "Save"
   • This is the #1 cause of access_denied errors!
2. API not enabled: Enable "Google Search Console API" in GCP Console
3. No access to the site: Verify you have access to the Search Console property you're querying

"Invalid site URL format"

Site URLs must be complete URLs like:

• https://example.com/ (for URL-prefix properties)
• sc-domain:example.com (for domain properties)

"Date range too old"

Search Console data is only available for the last 16 months.

"Rate limit exceeded"

The tool will automatically retry with backoff. If you continue to hit limits:

• Wait a few minutes between requests
• Reduce rowLimit in analytics queries
• API Limits: 2,000 requests/day, 600 requests/100 seconds

Token Expired

If you see authentication errors, your refresh token may have expired. Re-run the authentication setup:

npx -y -p google-search-console-mcp-server google-search-console-mcp-setup

Copy the new GOOGLE_REFRESH_TOKEN to your .mcp.json.

Development

Build

npm run build

Watch Mode

npm run dev

Re-authenticate

node build/auth/setup-auth.js

Project Structure

src/
├── index.ts                 # MCP server entry point
├── auth/
│   ├── google-auth.ts       # OAuth 2.0 client
│   └── setup-auth.ts        # Authentication CLI
├── tools/
│   ├── list-sites.ts        # List sites tool
│   ├── get-analytics.ts     # Search analytics tool
│   ├── get-sitemaps.ts      # Sitemap info tool
│   ├── inspect-url.ts       # URL inspection tool
│   ├── submit-url.ts        # Submit URL for indexing
│   └── compare-periods.ts   # Compare time periods
├── types/
│   └── index.ts             # Type definitions
└── utils/
    └── error-handler.ts     # Error handling & validation

Security Notes

• Never commit .env or .mcp.json files to version control
• Keep your refresh token secure
• Use readonly scope (webmasters.readonly) when possible
• Refresh tokens provide persistent access - store them securely

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

---

Resources

• Google Search Console API Documentation
• Model Context Protocol
• Claude Code Documentation