ga-gsc-analytics

Read-only MCP server exposing Google Analytics 4 and Google Search Console data (analytics.readonly + webmasters.readonly scopes) to Claude Code / Codex.

New here? Follow ONBOARDING.md for a zero-to-working walkthrough (install Claude Code, get credentials, authorize, verify). The rest of this file is reference material.

AI agents: this file doubles as AGENTS.md — start here for setup, then read skills/analyze-ga-gsc/SKILL.md for how to use the tools (access checks, default date ranges, GA4 vs. GSC semantics, presentation handoff format). Never ask a user to paste credentials into chat.

Tools

• analytics_auth_start / analytics_auth_status — local OAuth flow + status check
• analytics_list_sources — list GA4 properties and GSC sites available to the authorized account
• ga_run_report — run a GA4 report
• gsc_query_search_analytics — query Search Console data
• analytics_presentation_snapshot — combined GA4 + GSC snapshot for reporting

Setup (per user)

Each user authorizes with their own Google account and keeps their own local token — never share client_secret.json secrets or tokens.json between machines.

1. Google Cloud OAuth client: create (or reuse an existing) OAuth 2.0 Desktop client in Google Cloud Console and download its client_secret.json. If the consent screen is in "Testing" publishing status, add each new user's Google account as a test user first, or auth will fail with access-denied.
2. Place the credentials at ~/.config/ga-gsc-analytics/client_secret.json (or point GA_GSC_CLIENT_SECRET at a custom path).
3. Grant data access: the authorizing Google account needs real permissions on the target GA4 property (Analytics Admin → Property Access Management) and the GSC site (Search Console → Settings → Users and permissions).
4. Build the server (only needed if you change mcp/server.mjs; the repo ships a prebuilt mcp/server.bundle.cjs):

   pnpm install
   pnpm run build   # bundles mcp/server.mjs -> mcp/server.bundle.cjs
   

5. Register the MCP server. Either:
   • Claude Code, user-level: claude mcp add ga-gsc-analytics -- node /path/to/ga-gsc-analytics/mcp/server.bundle.cjs
   • Claude Code / Codex, project-scoped: this repo already ships a relative .mcp.json ({"mcpServers": {"ga_gsc_analytics": {"command": "node", "args": ["./mcp/server.bundle.cjs"]}}}) — copy it into a project, or symlink/vendor this whole folder in, and it's picked up automatically when that project is opened.
6. Authorize: call the analytics_auth_start tool from within your AI tool — it opens a local browser OAuth flow and writes ~/.config/ga-gsc-analytics/tokens.json.
7. Verify: call analytics_auth_status (should report authorized: true), then analytics_list_sources to confirm the expected GA4 properties / GSC sites show up.

Config overrides

Env var	Default
GA_GSC_CONFIG_DIR	~/.config/ga-gsc-analytics
GA_GSC_CLIENT_SECRET	$GA_GSC_CONFIG_DIR/client_secret.json
GA_GSC_TOKEN_PATH	$GA_GSC_CONFIG_DIR/tokens.json

Development

pnpm run check   # syntax check
pnpm test        # node --test tests/*.test.mjs