Google SEO MCP Server API - v1.13.5
    Preparing search index...

    Google SEO MCP Server API - v1.13.5

    Google SEO MCP

    A Model Context Protocol (MCP) server that transforms how you interact with Google Search Console and Google Analytics 4. Stop exporting CSVs and start asking questions.

    📚 View Documentation

    License: MIT Tests

    • Data Silos: Manually checking Google, then GA4.
    • Manual Correlation: Exporting different CSVs and using VLOOKUPs to see if your #1 ranking page actually converts.
    • Switching Fatigue: Logging in and out to manage multiple clients or properties.
    • AI Context Limits: Uploading giant spreadsheets that hit context limits and cause model hallucinations.
    • Platform Synergy: GSC + GA4 in a single context window. Stop exporting, start analyzing.
    • Deterministic Intelligence: The server performs the complex SEO math (cannibalization, Z-score anomalies, striking distance) so your AI agent gets curated insights, not raw data piles.
    • Cross-Platform ROI: Use the Opportunity Matrix to prioritize keywords that have high search visibility (GSC) but poor on-site engagement (GA4).
    • Zero-Config Multi-Account: Connect 20+ accounts. The server automatically resolves the correct credentials for every site URL.

    One Server. Two Platforms. Infinite Accounts. Actionable Intelligence.

    Copy and paste these into your MCP client (Claude Desktop, etc.) to see the intelligence engine in action:

    "My traffic dropped this week compared to last. Use the anomaly detection and time-series tools to find exactly when the drop started and which pages are responsible."

    "Find keywords for https://example.com where I'm ranking in positions 8-15 but have at least 1,000 impressions. These are my best opportunities for a quick traffic boost."

    "Check for keyword cannibalization. Are there any queries where two or more of my pages are competing and splitting the traffic? Suggest which one should be the primary authority."

    "Analyze my top 50 keywords for the last 90 days. Rank them by a custom 'Opportunity Score' (Impressions / Position). Give me the top 5 specific pages to focus on."

    "Run a full SEO health check for my site. Segment the results by Brand vs. Non-Brand and give me 3 high-impact actions for the upcoming week."

    "Fetch the top 5 pages by impressions. For these pages, run a PageSpeed audit. Is there any correlation between low performance scores and recently declining positions?"

    "Run an opportunity_matrix for my top 20 pages. Which high-visibility pages have the lowest engagement or conversion rates? These are my conversion optimization priorities."

    Google SEO MCP uses a Secure Desktop Flow. This provides high-security, professional grade authentication for your Google account:

    • Multi-Account Support: Connect multiple Google accounts. The server automatically picks the right one for each site.
    • System Keychain Primary: Tokens are stored in your OS's native credential manager (macOS Keychain, Windows Credential Manager, or Linux Secret Service).
    • AES-256-GCM Hardware-Bound Encryption: Fallback storage is encrypted with AES-256-GCM using a key derived from your unique hardware machine ID. Tokens stolen from your machine cannot be decrypted on another computer.
    • Silent Background Refresh: Tokens auto-refresh silently when they expire.

    For local desktop use, run the following command to start the authorization process:

    npx google-seo-mcp setup

    The CLI will:

    1. Briefly start a secure local server to handle the redirect.
    2. Open your default web browser to the Google Authorization page.
    3. Automatically fetch your email after authorization to label your credentials securely.

    If you host this MCP server centrally (using Express SSE mode), you can authenticate your Google Account directly via the web browser.

    1. Prerequisite: Set your custom Google OAuth Credentials as environment variables:
      export GOOGLE_CLIENT_ID="your-google-client-id"
      export GOOGLE_CLIENT_SECRET="your-google-client-secret"
    2. Register callback: Ensure you register your server's callback URI in the Google Cloud Console: https://mcp.yourcompany.com/search-console/oauth2callback (replace with your custom domain and BASE_PATH).
    3. Trigger Auth: Visit https://mcp.yourcompany.com/search-console/setup in your browser. This will redirect you to Google to log in and authorize the requested scopes.
    4. Complete: Google will redirect you back to the server which automatically saves the OAuth tokens.

    Note: You can authorize multiple accounts by visiting this endpoint again and signing in with different Google accounts.

    🔑 Step 2 — Logout & Management

    To wipe your credentials from both the keychain and the disk:

    # Logout of the default account
    npx google-seo-mcp logout

    # Logout of a specific account
    npx google-seo-mcp logout user@gmail.com

    For server-side environments or automated tasks where interactive login isn't possible, you can use a Google Cloud Service Account.

    1. Create Service Account: Go to the Google Cloud Console and create a service account.
    2. Generate Key: Click "Keys" > "Add Key" > "Create new key" (JSON). Download this file.
    3. Share Access: In Google Search Console, add the service account's email address (e.g., account@project.iam.gserviceaccount.com) as a user with at least "Full" or "Restricted" permissions.
    4. Configure: Point the server to your key file:
      export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/key.json"

    Connect your GA4 properties to correlate ranking data with user behavior. GA4 can be authorized using either authentication flow:

    If you used Option B (Express Web OAuth), the scopes for GA4 read-only access were already requested and authorized during that process! Both Search Console and GA4 will immediately work for that account.

    If using a service account:

    1. Share Access: Add the service account's email address in GA4 Admin > Property Settings > Property Access Management (grant at least Viewer/Analyst permissions).
    2. Configure Key: Set the key path in your environment variables:
      export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/key.json"

    Manage multiple Google accounts from the CLI:

    # List all connected accounts
    npx google-seo-mcp accounts list

    # Remove an account
    npx google-seo-mcp accounts remove --account=marketing@company.com

    # Add a site boundary to an account
    npx google-seo-mcp accounts add-site --account=marketing@company.com --site=example.com

    When your AI agent queries a site, the server automatically resolves which account to use. Learn more →

    This MCP server implements a multi-layered security architecture:

    • Keychain Integration: Primarily uses the macOS Keychain, Windows Credential Manager, or libsecret (Linux) to store tokens.
    • Encrypted Config: Account configuration is stored in ~/.google-seo-mcp-config.enc using AES-256-GCM encryption.
    • Machine Fingerprinting: The encryption key is derived from your unique hardware UUID and OS user. The encrypted file is useless if moved to another machine.
    • Minimalist Storage: Only the refresh_token and expiry_date are stored.
    • Legacy Support: Automatically detects credentials from older versions (tokens files, environment variables).
    • Strict Unix Permissions: Config files are created with mode 600 (read/write only by your user).
    Tool Description
    analytics_query Master tool for raw data. Supports dimensions, filters, aggregationType (byPage/byProperty), dataState (final/all), and type (web/image/news/discover).
    analytics_trends Detect trends (rising/falling) for specific queries or pages.
    analytics_anomalies Detect statistical anomalies in daily traffic.
    analytics_drop_attribution [NEW] Attribute traffic drops to mobile/desktop or correlate with known Google Algorithm Updates.
    analytics_time_series [NEW] Advanced time series with rolling averages, seasonality detection, and forecasting.
    analytics_compare_periods Compare two date ranges (e.g., WoW, MoM).
    seo_brand_vs_nonbrand [NEW] Analyze performance split between Brand vs Non-Brand traffic.
    Tool Description
    seo_low_hanging_fruit Find keywords ranking in pos 5-20 with high impressions.
    seo_striking_distance [NEW] Find keywords ranking 8-15 (Quickest ROI wins).
    seo_low_ctr_opportunities [NEW] Find top ranking queries (pos 1-10) with poor CTR.
    seo_cannibalization [Enhanced] Detect pages competing for the same query with traffic conflict.
    seo_lost_queries [NEW] Identify queries that lost all traffic in the last 28 days.

    These are low-level tools designed to be used by other AI agents to build complex logic.

    Tool Description
    seo_primitive_ranking_bucket Categorize a position (e.g. "Top 3", "Page 1", "Unranked").
    seo_primitive_traffic_delta Calculate absolute and % change between two numbers.
    seo_primitive_is_brand Check if a query matches a brand regex.
    seo_primitive_is_cannibalized Check if two pages are competing for the same query.
    Tool Description
    sites_list List all verified sites.
    sites_add / sites_delete Manage properties.
    sites_health_check [NEW] Run a health check on one or all sites. Checks WoW performance, sitemaps, and anomalies.
    sitemaps_list / sitemaps_submit Manage sitemaps.
    Tool Description
    inspection_inspect Google URL Inspection API (Index status, mobile usability).
    pagespeed_analyze Lighthouse scores & Core Web Vitals.
    schema_validate Validate Structured Data (JSON-LD).
    Tool Description
    analytics_page_performance Detailed page metrics (sessions, engagement, views).
    analytics_traffic_sources Analyze sessions by Channel, Source, and Medium.
    analytics_organic_landing_pages Focused metrics for organic traffic landing pages.
    analytics_content_performance Analyze content performance by Content Group in GA4.
    analytics_conversion_funnel Top converting pages and events.
    analytics_user_behavior Device, Country, and Engagement breakdown.
    analytics_audience_segments New vs Returning, Age, and OS analysis.
    analytics_realtime Live active user data by page and location.
    analytics_ecommerce Product and revenue performance.
    analytics_pagespeed_correlation Correlate GA4 metrics with PageSpeed scores.
    Tool Description
    opportunity_matrix [Flagship] Prioritize SEO tasks by combining signals from GSC and GA4.
    page_analysis Joint analysis of ranking (GSC) vs behavior (GA4) for pages.
    traffic_health_check Diagnose tracking gaps by comparing GSC clicks to GA4 organic sessions.
    brand_analysis Brand vs Non-Brand split across GSC and GA4.

    MIT Contributing

    Settings

    Member Visibility

    On This Page

    Google SEO MCP