🔍 google-seo-mcp

Full Google SEO & analytics stack for AI agents — over one MCP server.

Search Console · Indexing API · GA4 (Admin + Data) · Tag Manager · PageSpeed Insights

A Model Context Protocol server that gives Claude (and any MCP client) hands-on control of the Google SEO and analytics stack — list and claim properties, query search performance, submit URLs for indexing, spin up GA4 properties and data streams (i.e. install the measurement tag), wire up Tag Manager, and run PageSpeed audits. Ships with self-configuring OAuth2: no tokens at launch — the agent walks through authorization with built-in tools.

✨ Highlights

• 🔎 Search Console — properties, sitemaps, search analytics, URL inspection
• ⚡ Indexing API — push URL_UPDATED / URL_DELETED notifications
• 📊 GA4 — create properties & web data streams (get the Measurement ID), run reports & realtime
• 🏷️ Tag Manager — accounts, containers, workspaces, tags
• 🚦 PageSpeed Insights — Core Web Vitals + Lighthouse, no OAuth needed
• 🔐 Self-configuring OAuth2 — loopback code capture + auto-refresh, stored locally
• 🛡️ Safety rails — read-only mode and per-call confirm guards

📦 Installation

Run straight from npm with npx (no install needed), or build from source:

# from source
git clone https://github.com/skiddgoddamn/google-seo-mcp
cd google-seo-mcp
npm install && npm run build

🔌 Connect to your MCP client

Add to your MCP config (e.g. ~/.claude.json or claude_desktop_config.json):

{
  "mcpServers": {
    "google-seo": {
      "command": "npx",
      "args": ["-y", "google-seo-mcp"],
      "env": { "GOOGLE_PSI_API_KEY": "" }
    }
  }
}

{
  "mcpServers": {
    "google-seo": {
      "command": "node",
      "args": ["F:/projects/google-seo-mcp/build/index.js"]
    }
  }
}

☁️ Google Cloud setup

1. Open Google Cloud Console → APIs & Credentials
2. Create an OAuth 2.0 Client ID → application type Desktop app
3. Enable these APIs for the project:
   • Google Search Console API · Indexing API · Analytics Admin API · Analytics Data API · Tag Manager API
4. On the OAuth consent screen, add your Google account as a test user (while the app is in "Testing")
5. Keep the Client ID and Client Secret handy

🔑 Authorize (self-setup)

No tokens needed at startup — run these tools from your agent, in order:

| Step | Tool | What happens | |------|------|--------------| | 1 | g_set_credentials | Save your OAuth Client ID + Client Secret | | 2 | g_authorize | Opens Google's consent screen and captures the code via a local loopback server | | ↳ | g_set_code | Headless fallback — paste the code + redirect URI manually | | ✓ | g_auth_status | Check what's configured and whether the token is valid |

The refresh token is saved to ~/.google-seo-mcp/config.json and reused (and auto-refreshed) on every run.

⚙️ Environment variables

| Variable | Default | Description | |---|---|---| | G_READONLY | false | Block every mutating tool (_add _create _update _delete _submit _set) | | G_CONFIRM | false | Require a confirm=true argument on mutating calls | | G_LOG_LEVEL | INFO | DEBUG · INFO · WARNING · ERROR | | G_LOG_BODIES | false | Log request/response bodies to stderr (verbose) | | G_LOG_FILE | — | Append log lines to a file (default: stderr only) | | GOOGLE_MCP_CONFIG_DIR | ~/.google-seo-mcp | Override the config directory | | GOOGLE_PSI_API_KEY | — | PageSpeed Insights key; anonymous (rate-limited) if unset |

See .env.example for a ready-to-copy template.

🧰 Tool reference

🔐 Auth — g_

| Tool | Description | |---|---| | g_auth_status | Show OAuth configuration status and token validity | | g_set_credentials | Save OAuth client_id and client_secret | | g_authorize | Open the consent screen via loopback and store the refresh token | | g_set_code | Manually exchange an authorization code for a refresh token |

🔎 Search Console — gsc_

| Tool | Description | |---|---| | gsc_sites_get | List all Search Console properties | | gsc_site_get | Get a single property and your permission level | | gsc_site_add | Add (claim) a property | | gsc_site_delete | Remove a property | | gsc_sitemaps_get | List submitted sitemaps | | gsc_sitemap_get | Get a sitemap's status | | gsc_sitemap_submit | Submit a sitemap | | gsc_sitemap_delete | Delete a sitemap | | gsc_search_analytics | Clicks / impressions / CTR / position by query, page, country, device, date | | gsc_url_inspect | Index status, coverage, mobile usability, rich results |

⚡ Indexing API — idx_

| Tool | Description | |---|---| | idx_url_submit | Notify Google a URL was added/updated (URL_UPDATED) | | idx_url_delete | Notify Google a URL was removed (URL_DELETED) | | idx_metadata | Latest indexing-notification metadata for a URL |

ℹ️ The Indexing API is officially eligible only for pages with JobPosting or BroadcastEvent structured data. Other URLs may be ignored.

📊 GA4 — ga4_

| Tool | Description | |---|---| | ga4_accounts_get | List Analytics accounts | | ga4_properties_get | List properties under an account | | ga4_property_get | Get a property | | ga4_property_create | Create a GA4 property | | ga4_datastreams_get | List a property's data streams | | ga4_datastream_create | Create a web data stream → returns the Measurement ID | | ga4_datastream_get | Get a data stream | | ga4_run_report | Run a report (metrics + dimensions over a date range) | | ga4_realtime | Run a realtime report |

🏷️ Tag Manager — gtm_

| Tool | Description | |---|---| | gtm_accounts_get | List GTM accounts | | gtm_containers_get | List containers under an account | | gtm_container_create | Create a container → returns its GTM-ID | | gtm_workspaces_get | List workspaces of a container | | gtm_tags_get | List tags in a workspace | | gtm_tag_create | Create a tag in a workspace |

🚦 PageSpeed Insights — psi_

| Tool | Description | |---|---| | psi_run | Analyze a URL — Core Web Vitals + Lighthouse (no OAuth required) |

🛡️ Safety rails

• G_READONLY=true — blocks every tool whose name contains _add _create _update _delete _submit _set. Reads still work.
• G_CONFIRM=true — mutating tools return a preview and require a follow-up call with confirm: true.

📄 License

MIT © skiddgoddamn