google-search-console-mcp

Google Search Console MCP Server

Connect Google Search Console data to Claude, Cursor and other MCP clients. Query your website's search performance data in natural language with access to all GSC dimensions and metrics.

Compatible with: Claude, Cursor and other MCP clients.

Prerequisites

Check your Python setup:

# Check Python version (need 3.8+)
python --version
python3 --version

# Check pip
pip --version
pip3 --version

Required:

• Python 3.8 or higher
• Google Search Console property with data
• Service account with Search Console API access

Step 1: Setup Google Search Console Credentials

Create Service Account in Google Cloud Console

• Go to Google Cloud Console
• Create or select a project:
  • New project: Click "New Project" → Enter project name → Create
  • Existing project: Select from dropdown
• Enable the Search Console API:
  • Go to "APIs & Services" → "Library"
  • Search for "Search Console API" → Click "Enable"
• Create Service Account:
  • Go to "APIs & Services" → "Credentials"
  • Click "Create Credentials" → "Service Account"
  • Enter name (e.g., "gsc-mcp-server")
  • Click "Create and Continue"
  • Skip role assignment → Click "Done"
• Download JSON Key:
  • Click your service account
  • Go to "Keys" tab → "Add Key" → "Create New Key"
  • Select "JSON" → Click "Create"
  • Save the JSON file - you'll need its path

Add Service Account to Search Console

• Get service account email:
  • Open the JSON file
  • Find the client_email field
  • Copy the email (format: [e-mail])
• Add to Search Console:
  • Go to Google Search Console
  • Select your property
  • Click "Settings" (gear icon)
  • Click "Users and permissions"
  • Click "Add User"
  • Paste the service account email
  • Select "Full" permission
  • Click "Add"

Find Your Search Console Property

• In Google Search Console, select your property
• The property URL will be in the format:
  • For domain properties: sc-domain:example.com
  • For URL-prefix properties: https://example.com/

Test Your Setup (Optional)

Verify your credentials:

pip install google-api-python-client

Create a test script (test_gsc.py):

import os
from google.oauth2 import service_account
from googleapiclient.discovery import build

# Set credentials path
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/path/to/your/service-account-key.json"

# Test connection
credentials = service_account.Credentials.from_service_account_file(
    os.environ["GOOGLE_APPLICATION_CREDENTIALS"],
    scopes=['https://www.googleapis.com/auth/webmasters.readonly']
)

service = build('searchconsole', 'v1', credentials=credentials)
print("✅ GSC credentials working!")

Run the test:

python test_gsc.py

If you see "✅ GSC credentials working!" you're ready to proceed.

Step 2: Install the MCP Server

Choose one method:

Method A: pip install (Recommended)

pip install google-search-console-mcp

MCP Configuration:

First, check your Python command:

python3 --version
python --version

Then use the appropriate configuration:

If python3 --version worked:

{
  "mcpServers": {
    "gsc-search": {
      "command": "python3",
      "args": ["-m", "gsc_mcp_server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GSC_SITE_URL": "https://example.com/"
      }
    }
  }
}

If python --version worked:

{
  "mcpServers": {
    "gsc-search": {
      "command": "python",
      "args": ["-m", "gsc_mcp_server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GSC_SITE_URL": "https://example.com/"
      }
    }
  }
}

Method B: GitHub download

git clone https://github.com/surendranb/google-search-console-mcp.git
cd google-search-console-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

MCP Configuration:

{
  "mcpServers": {
    "gsc-search": {
      "command": "/full/path/to/google-search-console-mcp/venv/bin/python",
      "args": ["/full/path/to/google-search-console-mcp/gsc_mcp_server.py"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GSC_SITE_URL": "https://example.com/"
      }
    }
  }
}

Step 3: Update Configuration

Replace these placeholders in your MCP configuration:

• /path/to/your/service-account-key.json with your JSON file path
• https://example.com/ with your Search Console property URL
• /full/path/to/google-search-console-mcp/ with your download path (Method B only)

Important Notes:

• For URL-prefix properties: Use https://example.com/ format
• For domain properties: Use sc-domain:example.com format
• Make sure the URL format exactly matches your Search Console property

Usage

Once configured, ask your MCP client questions like:

Search Performance Analysis

• What's my website's search performance for the past week?
• Show me clicks and impressions by country for last month
• Compare CTR between different date ranges

Keyword Analysis

• What are my top-performing keywords by clicks?
• Show me average position by query and device
• Analyze search appearance by query type

Page Performance

• What are my top pages by impressions?
• Show me CTR by page and device type
• Analyze search performance by content type

Multi-Dimensional Analysis

• Show me clicks and impressions by country and device
• Analyze search performance by query and page
• Compare performance across different search appearances

Quick Start Examples

Try these example queries to see the MCP's analytical capabilities:

1. Geographic Distribution

Show me a map of search impressions by country for the last 30 days, with a breakdown of clicks vs impressions

This demonstrates:

• Geographic analysis
• Performance metrics
• Time-based filtering
• Data visualization

2. Keyword Performance

Compare average position and CTR by query and device type over the last 90 days

This demonstrates:

• Multi-dimensional analysis
• Time series comparison
• Search metrics
• Device segmentation

3. Page Performance

Show me clicks and impressions by page, comparing last 30 days vs previous 30 days

This demonstrates:

• Content analysis
• Period-over-period comparison
• Performance tracking
• Page attribution

4. Search Appearance

What are my top 10 search appearances by CTR, and how has their performance changed over the last 3 months?

This demonstrates:

• Feature analysis
• Trend analysis
• Performance metrics
• Ranking and sorting

Available Tools

The server provides 7 main tools:

• list_gsc_sites - List all verified sites in your Search Console
• list_available_dimensions - Show all available GSC dimensions
• list_available_metrics - Show all available GSC metrics
• get_search_analytics - Retrieve search performance data with custom filters
• get_sitemaps - List all submitted sitemaps for your site
• submit_sitemap - Submit a new sitemap to Search Console
• delete_sitemap - Remove a sitemap from Search Console

Dimensions & Metrics

Access to all GSC dimensions and metrics:

Available Dimensions

• country: Three-letter ISO 3166-1 alpha-3 country code
• device: DESKTOP, MOBILE, or TABLET
• page: Canonical URL of the page
• query: Search query string
• searchAppearance: Type like AMP_BLUE_LINK, RICHCARD, FEATURED_SNIPPET
• date: Date in YYYY-MM-DD format

Available Metrics (Always Returned)

• clicks: Total number of clicks
• impressions: Total number of impressions
• ctr: Click-through rate as percentage
• position: Average search position

Troubleshooting

If you get "No module named gsc_mcp_server" (Method A):

pip3 install --user google-search-console-mcp

If you get "executable file not found":

• Try the other Python command (python vs python3)
• Use pip3 instead of pip if needed

Permission errors:

# Try user install instead of system-wide
pip install --user google-search-console-mcp

Credentials not working:

• Verify the JSON file path is correct and accessible
• Check service account permissions:
  • Go to Google Cloud Console → IAM & Admin → IAM
  • Find your service account → Check permissions
• Verify Search Console access:
  • Search Console → Settings → Users and permissions
  • Check for your service account email
• Verify property format:
  • Domain property: sc-domain:example.com ✅
  • URL-prefix property: https://example.com/ ✅

API quota/rate limit errors:

• Search Console has daily quotas and rate limits
• Try reducing the date range in your queries
• Wait a few minutes between large requests

Project Structure

google-search-console-mcp/
├── gsc_mcp_server.py       # Main MCP server
├── gsc_dimensions.json     # GSC dimensions configuration
├── gsc_metrics.json        # GSC metrics configuration
├── gsc_filters.json        # GSC filters configuration
├── requirements.txt        # Python dependencies
├── pyproject.toml          # Package configuration
├── README.md              # Documentation
├── claude-config-template.json  # MCP configuration template
└── logo.svg               # Project logo

License

MIT License