GA4 MCP Server

Production-ready, multi-tenant Google Analytics 4 MCP server for Claude.

This is the first connector in a larger platform. Shared infrastructure (auth, clients, Google OAuth token storage, authorization, logging, errors) is reusable. GA4-specific code stays under src/connectors/ga4 and src/mcp/ga4. Do not treat this as a monolithic Google Marketing MCP.

Architecture

Claude
  |  MCP OAuth 2.1 + Streamable HTTP
  v
Next.js / Vercel  (/mcp)
  |-- MCP tools (ga4_*)
  |-- Authorization (client_members only)
  |-- GA4 service
  |-- Google OAuth token manager
  v
Supabase
  |-- clients
  |-- client_members   (application identity)
  |-- google_connections (Google credential, not app identity)
  |-- ga4_properties

Application users are Supabase Auth users. Tenant access is only client_members(user_id, client_id, role). A Google-connected account is a client-owned credential and is never the application user.

Local setup

npm install
cp .env.example .env.local
# fill in the values documented below
npx supabase start   # or link a remote project
npx supabase db reset --local
npm run dev

Open http://localhost:3000, create an application account, create a client, then connect Google Analytics.

Google Cloud setup

1. Create or select a Google Cloud project.
2. Enable Google Analytics Data API and Google Analytics Admin API.
3. Configure the OAuth consent screen (External or Internal).
4. Create OAuth 2.0 Client ID credentials (Web application).
5. Authorized redirect URI:
   • Local: http://localhost:3000/api/auth/google/callback
   • Production: https://<your-domain>/api/auth/google/callback
6. Request only GA4 scopes:
   • https://www.googleapis.com/auth/analytics.readonly
   • openid
   • email

Do not add DV360 or Google Ads scopes to this connector.

GA4 setup

1. Sign in to this app with email/password (application identity).
2. Create a client (you become owner in client_members).
3. Optionally add other application users as owner or member.
4. Click Connect Google Analytics. This attaches a Google credential to the client.
5. Link one or more GA4 properties discovered from that Google account.

A member who did not click Connect can still query the client if they have a client_members row.

Supabase setup

This repo includes SQL migrations in supabase/migrations. Create them with the CLI; do not invent filenames.

Local:

npx supabase start
npx supabase db reset --local

Remote:

npx supabase link --project-ref <project-ref>
npx supabase db push

The service role key is server-only. Never expose SUPABASE_SERVICE_ROLE_KEY or Google refresh tokens to the browser.

Environment variables

See .env.example. Required:

Variable	Purpose
NEXT_PUBLIC_SUPABASE_URL	Supabase project URL
NEXT_PUBLIC_SUPABASE_ANON_KEY	Browser/server user client
SUPABASE_SERVICE_ROLE_KEY	Server-side admin (never NEXT_PUBLIC_)
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	Google OAuth app
GOOGLE_REDIRECT_URI	Must match Google Cloud
GOOGLE_OAUTH_SCOPES	GA4-only scopes
MCP_BASE_URL	Public origin, e.g. https://your-app.vercel.app
MCP_TOKEN_SIGNING_SECRET	Signs MCP access tokens
TOKEN_ENCRYPTION_KEY	64 hex chars (32 bytes) for Google token encryption

Do not put a GA4 property ID in .env. Properties belong to clients in Supabase.

Generate a token encryption key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

MCP setup (Claude)

Remote endpoint:

https://<your-domain>/mcp

This server implements MCP OAuth 2.1:

• Protected resource metadata: /.well-known/oauth-protected-resource
• Authorization server metadata: /.well-known/oauth-authorization-server
• Authorize: /oauth/authorize (application login + consent)
• Token: /oauth/token (authorization_code + refresh_token, PKCE S256)
• Register: /oauth/register (DCR fallback)
• CIMD is advertised (client_id_metadata_document_supported)

In Claude: Settings → Connectors → Add custom connector → paste https://<your-domain>/mcp. Claude will run OAuth. After you approve, tools are available.

Local inspector:

npx @modelcontextprotocol/inspector

Connect with Streamable HTTP to http://localhost:3000/mcp. You still need a valid MCP Bearer token from the OAuth flow.

Tools

Tool	Purpose
ga4_run_report	Primary report (dates, metrics, dimensions, limit, order, basic filter)
ga4_realtime	Realtime active users / traffic breakdown
ga4_metadata	Discover metrics and dimensions for a property
ga4_list_properties	Properties visible to the client's Google connection
ga4_compare_periods	Current vs previous period with abs/% change

Every tool requires client_id. Property-scoped tools also require a linked property_id. Authorization always checks client_members before Google is called.

Example: ga4_run_report

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "date_start": "2026-08-01",
  "date_end": "2026-08-15",
  "dimensions": ["country"],
  "metrics": ["activeUsers", "sessions", "totalRevenue"],
  "limit": 10
}

Example: ga4_compare_periods

{
  "client_id": "11111111-1111-1111-1111-111111111111",
  "property_id": "123456789",
  "current_start": "2026-08-01",
  "current_end": "2026-08-15",
  "previous_start": "2026-07-17",
  "previous_end": "2026-07-31",
  "metrics": ["activeUsers", "sessions", "totalRevenue"]
}

Claude can then answer questions such as:

• How many users did we have yesterday?
• Top 10 countries this month
• Compare this month with last month
• How many active users are on the site right now?

Testing

npm test

Tests use mocked Google and Supabase. They never use production OAuth tokens.

Vercel

Deploy the Next.js app and set the same environment variables. MCP_BASE_URL and GOOGLE_REDIRECT_URI must use the production domain. The /mcp route runs on the Node.js runtime with a 60s max duration.

Project layout

src/
  auth/              application authentication
  authorization/     authorizeClient via client_members
  oauth/             Google OAuth + token manager
  mcp-oauth/         MCP OAuth 2.1 authorization server
  connectors/ga4/    Google Analytics APIs
  mcp/ga4/           MCP tools
  repositories/      Supabase data access
  app/mcp/           Streamable HTTP transport

Future connectors (DV360, Google Ads) should add src/connectors/<name> and src/mcp/<name> and reuse the shared core. Do not create a generic Google API dumping ground.