<div align="center">

🔍 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

</div>

---

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": "" }
    }
  }
}

<details> <summary>Or point at a local build</summary>

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

</details>

☁️ 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