@hub40/ga-gsc-mcp

MCP server for Google Analytics 4 + Google Search Console with OAuth multi-account login. Built for SEO consultants managing many client properties.

One desktop-OAuth consent grants access to both GSC sites and GA4 properties. Setup remembers every property you authorize, so an AI agent in Claude Desktop can answer questions like "top 5 organic landing pages of superepi.com.br last 30 days" without you juggling credentials.

Quick start

npm install -g @hub40/ga-gsc-mcp
ga-gsc-mcp setup --engine=ga4

The browser opens, you authorize with your Google account, pick the GA4 properties you want to manage (or type 0 to grab all of them), and tokens are stored encrypted in your OS keychain.

Then add the MCP to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "ga-gsc": {
      "command": "ga-gsc-mcp"
    }
  }
}

Restart Claude Desktop. Ask list accounts in ga-gsc to verify the tools loaded.

Features

• OAuth 2.0 desktop flow — browser consent, refresh tokens refresh automatically
• Multi-account, multi-property — one login can authorize N properties; the resolver maps domain URLs and numeric IDs back to the right credentials
• Multi-select setup — 0 for all properties, 1,3,5 for a subset, or single index
• Web Data Stream URL enrichment — GA4 properties surface as their real domain (https://www.example.com), not just a numeric ID
• Encrypted token storage — tokens go to the OS keychain (Windows Credential Manager / macOS Keychain / Linux Secret Service) plus an AES-256-GCM encrypted config file
• GSC, GA4, PageSpeed, and cross-platform SEO analysis (cannibalization, striking-distance, opportunity matrix, etc.)
• Full parity with the official Google Analytics MCP — Admin API (analytics_account_summaries, analytics_property_details, analytics_google_ads_links, analytics_custom_definitions) plus generic Data API tools (analytics_run_report, analytics_run_realtime_report) sit alongside our 10 SEO-opinionated GA4 tools

Migration from 1.x

Bing Webmaster Tools support was removed in 2.0 to reduce the LLM context cost of Bing tool registrations our team wasn't using. If you still need Bing, pin to the previous major: npm install -g @hub40/ga-gsc-mcp@^1.

The startup will refuse to load if a stale config still has accounts with engine: 'bing'. Run ga-gsc-mcp accounts remove --account=<alias> for each, or pin to v1.

CLI commands

| Command | What it does | |---|---| | ga-gsc-mcp setup --engine=ga4 | Add Google Analytics 4 properties | | ga-gsc-mcp setup --engine=google | Add Google Search Console sites | | ga-gsc-mcp accounts list | List configured accounts (JSON) | | ga-gsc-mcp accounts remove --account=<alias_or_id> | Remove an account | | ga-gsc-mcp accounts add-site --account=<alias> --site=<url> | Add a site boundary to an account |

Multi-select GA4 setup

When you run ga-gsc-mcp setup --engine=ga4 and your Google account has multiple GA4 properties, you see:

Found 12 properties:
  [0] [All Properties]
  [1] World E-commerce - GA4 (346657235)
  [2] Blog da World Importados - GA4 (346739488)
  [3] Super EPI - GA4 (339605582)
  ...
  [M] Enter manually

Select property (1-12), 0 for all, comma-separated (e.g. 1,3,5), or M:

Pick one, a subset, or all — the setup iterates through each, runs a quick runReport smoke test, fetches each property's Web Data Stream URLs, and stores one account entry per property. Re-running setup updates existing entries idempotently (preserves your aliases).

Claude Desktop config options

Simplest (global install)

{
  "mcpServers": {
    "ga-gsc": {
      "command": "ga-gsc-mcp"
    }
  }
}

Without global install (npx)

{
  "mcpServers": {
    "ga-gsc": {
      "command": "npx",
      "args": ["-y", "@hub40/ga-gsc-mcp"]
    }
  }
}

Note: first invocation downloads the package (~30s). The global install avoids this cost and is recommended for Claude Desktop since the MCP initialization has a 60s handshake timeout.

Override embedded OAuth credentials

The published package ships with hub40/liveSEO's OAuth app credentials so npx works zero-config. Override via env in the Claude Desktop config (or via .env / shell env vars) if you want to use your own GCP OAuth project:

{
  "mcpServers": {
    "ga-gsc": {
      "command": "ga-gsc-mcp",
      "env": {
        "GOOGLE_CLIENT_ID": "your-own-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-own-secret"
      }
    }
  }
}

Data lineage

| What | Where | |---|---| | Encrypted config | ~/.search-console-mcp-config.enc (AES-256-GCM, key derived from machine ID) | | OAuth tokens | OS keychain, service io.hub40.ga-gsc-mcp, keyed by account alias |

Delete ~/.search-console-mcp-config.enc to start fresh (also clears the lazy-migrated legacy files ~/.search-console-mcp-tokens.enc and ~/.search-console-mcp-tokens.json if present).

Requirements

• Node.js ≥ 18 (tested on 20 and 21)
• A Google account with access to the GA4 properties or GSC sites you want to manage

Troubleshooting

"Access blocked: liveSEO GA e GSC has not completed the Google verification process" The Google account running setup needs to be added as a Test User in the OAuth consent screen of the underlying GCP project. If you're running the published package as-is, contact the package maintainer. If you're running your own fork, add the email at https://console.cloud.google.com/apis/credentials/consent.

"PERMISSION_DENIED: User does not have sufficient permissions for this property" Your Google account doesn't have access to the GA4 property ID you queried. Verify in GA4 Admin → Property Access Management. Note: the API returns the same error for both "no access" and "property doesn't exist", so double-check the property ID too.

"Unexpected token ... is not valid JSON" from Claude Desktop A dependency is printing to stdout instead of stderr, corrupting the JSON-RPC protocol. This package silences known offenders (dotenv), but if you see it with a specific tool, open an issue.

Command ga-gsc-mcp not recognized after npm install -g C:\Users\<you>\AppData\Roaming\npm\ (Windows) or $(npm bin -g) (Unix) must be in your PATH. This is npm's default but some environments override it.

Development

git clone https://github.com/<org>/ga-gsc-mcp
cd ga-gsc-mcp
npm install
cp .env.example .env  # add your own GCP OAuth credentials for dev
npm run build
node dist/setup.js --engine=ga4

Credits

This package is a fork of search-console-mcp by Saurabh Sharma, released under the MIT license. The hub40/liveSEO fork adds OAuth multi-account login for GA4, Web Data Stream URL enrichment, multi-select property setup, and team-distribution patterns.

If you find this useful, consider starring the original project — it's the foundation of 90% of what you're using.

License

MIT. See LICENSE for the original upstream copyright and this fork's additions.