# Google Webmaster MCP

[![npm version](https://img.shields.io/npm/v/google-webmaster-mcp.svg)](https://www.npmjs.com/package/google-webmaster-mcp)

Local MCP server and CLI toolkit for Google Search Console, Google Tag Manager, GA4, sitemap, and SEO audit workflows.

`google-webmaster-mcp` is intended to be project-agnostic: bring your own Google OAuth credentials, Search Console property, GTM container, and GA4 property. It does not depend on Ehukai Media websites or services.

## What It Does

- Runs an MCP stdio server with tools for GSC, GTM, and GA4. Google Business Profile tools are optional and off by default.
- Provides global CLI commands for audits, sitemap submission, GTM validation, GA4 setup, and GTM publishing.
- Includes `seo-audit` for bounded technical SEO checks against a URL.
- Stores OAuth tokens in the user config directory at `~/.config/google-webmaster-mcp/`.

## Install

### From npm

```bash
npm install -g google-webmaster-mcp
```

### From Source (Local Development)

```bash
git clone https://github.com/ehukaimedia/google-webmaster-mcp.git
cd google-webmaster-mcp
npm ci
npm run build
npm install -g .
```

## Configure Authentication

Create an OAuth Desktop App in Google Cloud, then provide the client ID and secret through your environment or a local `.env` file:

```env
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
```

Authenticate once per Google account/profile:

```bash
google-webmaster-mcp-auth
google-webmaster-mcp-auth --profile=client_a
```

To use a saved profile for CLI or MCP runs:

```bash
export GOOGLE_TOKEN_PROFILE=client_a
```

Token files are stored under `~/.config/google-webmaster-mcp/` with private file permissions.

## Configure Project Context

Run CLI commands from a project directory with these environment variables available:

```env
GTM_ID=GTM-XXXXXXX
GSC_SITE=sc-domain:example.com
GA4_PROPERTY_ID=123456789
GA4_MID=G-XXXXXXXXXX
GTM_WORKSPACE_ID=
GOOGLE_WEBMASTER_MCP_API_KEY=
```

`GA4_PROPERTY_ID` is the numeric GA4 property ID. `GA4_MID` is the `G-` measurement ID. `GTM_WORKSPACE_ID` is optional unless the container has multiple workspaces.

## Google Business Profile (off by default)

GBP tools stay hidden until Google approves Business Profile API access for the Cloud project (quota 300 QPM, not 0). Leave the switch off until then:

```env
GBP_ENABLED=false
```

After approval, turn it on and re-auth so the token includes `business.manage`:

```env
GBP_ENABLED=true
GBP_ACCOUNT_ID=
GBP_LOCATION_ID=
```

```bash
GBP_ENABLED=true google-webmaster-mcp-auth --profile=client_a
```

MCP client example with the switch on:

```json
{
  "mcpServers": {
    "google-webmaster": {
      "command": "npx",
      "args": ["-y", "google-webmaster-mcp"],
      "env": {
        "GBP_ENABLED": "true"
      }
    }
  }
}
```

## MCP Client Config

Use `npx` for portable MCP client registration:

```json
{
  "mcpServers": {
    "google-webmaster": {
      "command": "npx",
      "args": ["-y", "google-webmaster-mcp"]
    }
  }
}
```

The MCP server starts over stdio. Use `google-webmaster-mcp --help` or `google-webmaster-mcp --version` for CLI metadata; run without flags only from an MCP-compatible client.

## AI Assistant Skill

This repo includes an agnostic Codex-style skill for assistants that operate Google Webmaster MCP:

```text
skills/google-webmaster-mcp/SKILL.md
```

The skill documents safe authentication, read-only checks, GTM rate limits, and confirmation points without relying on any Ehukai Media-specific project.

## CLI Commands

```bash
google-webmaster-audit [GTM_ID] [GSC_SITE] [GA4_PROPERTY_ID]
google-webmaster-submit-sitemap [GSC_SITE] [SITEMAP_URL]
google-webmaster-gtm-validate [GTM_ID]
google-webmaster-setup-ga4 [GTM_ID] [GA4_MID]
google-webmaster-gtm-publish [GTM_ID] [VERSION_NOTES]
seo-audit <url> [--ai] [--pagespeed]
seo-audit --file urls.txt [--ai] [--pagespeed]
seo-audit-smart "audit localhost with AI"
```

All public commands support `--help` and `--version`.

## GTM Rate-Limit Safety

The GTM API has strict per-user quotas. Wait at least 3 minutes between GTM commands such as validate, setup, and publish. After a 429, stop and wait 3-5 minutes before one retry.

Safe sequence:

```bash
google-webmaster-audit
# wait 3 minutes
google-webmaster-gtm-validate
# wait 3 minutes
google-webmaster-setup-ga4
# wait 3 minutes
google-webmaster-gtm-validate
# wait 3 minutes
google-webmaster-gtm-publish
```

## Development

```bash
npm ci
npm run build
npm test
npm run audit:deps
npm run secrets:check
npm run pack:check
npm run smoke:tarball
```

Full local release gate:

```bash
npm run ci
```

## Security

Do not commit OAuth client secrets, `.env` files, or token files. See `SECURITY.md` for vulnerability reporting.

## License

ISC