google-search-console-mcp 0.2.0

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

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

1. Go to Google Cloud Console
2. Create or select a project:
   • New project: Click "New Project" → Enter project name → Create
   • Existing project: Select from dropdown
3. Enable the Search Console API:
   • Go to "APIs & Services" → "Library"
   • Search for "Search Console API" → Click "Enable"
4. 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"
5. 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

1. Get service account email:
   • Open the JSON file
   • Find the client_email field
   • Copy the email (format: [e-mail])
2. 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

1. In Google Search Console, select your property
2. 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_PROPERTY": "sc-domain: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_PROPERTY": "sc-domain: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_PROPERTY": "sc-domain: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
• sc-domain:example.com with your Search Console property
• /full/path/to/gsc-mcp-server/ with your download path (Method B only)

---

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 5 main tools:

1. get_gsc_data - Retrieve GSC data with custom dimensions and metrics
2. list_dimension_categories - Browse available dimension categories
3. list_metric_categories - Browse available metric categories
4. get_dimensions_by_category - Get dimensions for a specific category
5. get_metrics_by_category - Get metrics for a specific category

---

Dimensions & Metrics

Access to all GSC dimensions and metrics organized by category:

Dimension Categories

• Time: date, month, year
• Geography: country, region
• Device: desktop, mobile, tablet
• Search Appearance: AMP, rich results, featured snippets
• Page: URL, type
• Query: search terms, query type
• And more categories

Metric Categories

• Performance: clicks, impressions, CTR, position
• Search Features: rich results, AMP, featured snippets
• Device Metrics: mobile vs desktop performance
• Geographic Metrics: country and region performance
• And more specialized metrics

---

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:

1. Verify the JSON file path is correct and accessible
2. Check service account permissions:
   • Go to Google Cloud Console → IAM & Admin → IAM
   • Find your service account → Check permissions
3. Verify Search Console access:
   • Search Console → Settings → Users and permissions
   • Check for your service account email
4. 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