<div align="center">

# 🔍 google-seo-mcp

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

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

[![npm version](https://img.shields.io/npm/v/google-seo-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/google-seo-mcp)
[![npm downloads](https://img.shields.io/npm/dm/google-seo-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/google-seo-mcp)
[![node](https://img.shields.io/node/v/google-seo-mcp?logo=node.js&logoColor=white)](https://nodejs.org)
[![license](https://img.shields.io/npm/l/google-seo-mcp?color=blue)](./LICENSE)
[![MCP](https://img.shields.io/badge/Model_Context_Protocol-stdio-6E56CF)](https://modelcontextprotocol.io)

</div>

---

A [Model Context Protocol](https://modelcontextprotocol.io) 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 &amp; web data streams (get the Measurement ID), run reports &amp; 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:

```bash
# 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`):

```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>

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

## ☁️ Google Cloud setup

1. Open [Google Cloud Console → APIs &amp; Credentials](https://console.cloud.google.com/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`](./.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](https://github.com/skiddgoddamn)