Tag Pilot GA4

Tag Pilot GA4 MCP

A free, read-only Model Context Protocol server for Google Analytics 4. Ask Claude, Cursor or any MCP client about your GA4 data: reports, funnels, realtime, property setup, and Tag Pilot tracking-health checks.

No Google Cloud setup, no API key to copy. You don't need a GCP project, OAuth client, service account or gcloud. Add the server, ask a GA4 question, and approve once in your browser.

claude mcp add ga4 -- npx -y @tagpilot/ga4-mcp

Get started

1. Install in your AI client (below). No configuration needed.
2. Ask something, e.g. *"Which GA4 properties do I have?"* The first time, a browser window opens (or your AI shows a link and a code like ABCD-1234):

• sign in to your free Tag Pilot account, or create one;
• check that the code matches and approve this computer;
• sign in with the Google account that can see your GA4 properties and allow *"See and download your Google Analytics data"*.

1. Ask again. You're connected; the computer shows up under Connected devices on the GA4 MCP page.

Install

Everything except the Claude Desktop extension runs the npm package with npx, so it needs Node.js 18 or newer. The server is also listed in the MCP Registry as io.github.tagpilot/ga4-mcp.

Claude Desktop

Download tagpilot-ga4-mcp.mcpb and double-click it (or drag it into Settings → Extensions), click Install and enable it. Leave the optional API key field empty. The extension bundles the server and runs on Claude Desktop's built-in Node.js.

Prefer the config file? In claude_desktop_config.json (Settings → Developer → Edit Config):

{

"mcpServers": { "ga4": { "command": "npx", "args": ["-y", "@tagpilot/ga4-mcp"] } } }

Claude Code

claude mcp add ga4 -- npx -y @tagpilot/ga4-mcp

Cursor

Use Add to Cursor, or add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{

"mcpServers": { "ga4": { "command": "npx", "args": ["-y", "@tagpilot/ga4-mcp"] } } }

VS Code

Use Install in VS Code, or run MCP: Add Server → *Command (stdio)* with npx -y @tagpilot/ga4-mcp.

Gemini CLI

gemini extensions install https://github.com/tagpilot/ga4-mcp

Other clients (Windsurf, Zed, …) take the same command and args.

Headless and CI: an API key instead

Where nobody can approve in a browser, create a key on the GA4 MCP page and set TAGPILOT_API_KEY=tpk_… in the server's environment (e.g. claude mcp add ga4 --env TAGPILOT_API_KEY=tpk_... -- npx -y @tagpilot/ga4-mcp). With a key, the device connect is skipped and only the Google sign-in link is shown.

How connecting works, and what Tag Pilot sees

your machine                              Tag Pilot                          Google

────────────────────────────────────── ─────────────────────────── ────────────────────── ga4-mcp makes a PKCE verifier ──► POST /v3/public/ga4/device (it never leaves your machine) returns a link + code ABCD-1234 any browser, any device: app.tagpilot.io/connect: log in, check the code, approve → creates a ga4:mcp key for this device → Google consent (read-only) ─► accounts.google.com …/ga4/oauth/callback ◄────── one-time code ga4-mcp polls for the result ──► POST /v3/public/ga4/device/token returns the device key + code ga4-mcp exchanges code + verifier ──► POST …/ga4/oauth/token ──► oauth2.googleapis.com device key + Google tokens saved in ~/.config/tagpilot/ga4-mcp/device.json (mode 600) GA4 API calls ─────────────────────────────────────────────────────► analytics*.googleapis.com

It works from any browser, like gh auth login: nothing listens on your machine, so it also works over SSH, in containers, in WSL or on a remote dev box. Open the link wherever you have a browser (even your phone) and approve; the server notices within a couple of seconds.

• Your GA4 data goes from your machine straight to Google. Reports, property settings and everything else the tools read never pass through Tag Pilot.
• Tag Pilot only brokers the token exchange. Its API adds Tag Pilot's Google OAuth client credentials to Google's token endpoint and returns Google's answer. It stores no Google tokens and never logs them. The only thing it holds is the one-time sign-in code from the Google callback, for at most 10 minutes until your machine collects it; that code is useless without the PKCE verifier that stays on your machine. It records only that an exchange happened and for which device (the "last used" time on your GA4 MCP page).
• Read-only. The only Google scope requested is analytics.readonly. None of the tools can change anything in GA4.
• Your credentials stay on your machine, in ~/.config/tagpilot/ga4-mcp/device.json (readable only by you): the device's own Tag Pilot key and the Google refresh token. Access tokens are refreshed through Tag Pilot about once an hour.
• Disconnecting: revoke the device under Connected devices on the GA4 MCP page to stop refreshes, run npx -y @tagpilot/ga4-mcp logout to delete the local credential, and remove the app's access at myaccount.google.com/permissions.

Tools

All tools are read-only. Property IDs are the numeric GA4 IDs (e.g. 123456789), not G-XXXX measurement IDs.

Report inputs

• Dates: YYYY-MM-DD, today, yesterday or NdaysAgo (e.g. 28daysAgo). Default: the last 28 full days. Up to 4 ranges; several ranges add a dateRange column.
• Dimensions and metrics: GA4 API names, e.g. date, eventName, sessionSourceMedium, pagePath, sessions, activeUsers, purchaseRevenue (full list).
• Filters: a list of conditions that must all match; {"any": [...]} groups conditions with OR, and "not": true negates one:

  [

{"field": "eventName", "op": "exact", "value": "purchase"}, {"field": "country", "op": "in_list", "values": ["Poland", "Germany"], "not": true}, {"any": [ {"field": "pagePath", "op": "begins_with", "value": "/shop"}, {"field": "pagePath", "op": "partial_regex", "value": "product"} ]} ]

Ops: exact, contains, begins_with, ends_with, full_regex, partial_regex, in_list, eq, lt, lte, gt, gte, between (from/to), empty. Dimension and metric filters are separate inputs, like in the GA4 API.

• Ordering: [{"field": "sessions", "desc": true}]. Use dimension_order: "numeric" for numeric-looking dimensions.
• Output: rows are objects such as {"date": "20261026", "sessions": 321}. Default limit is 100 rows; next_offset tells you when there are more. Thresholding, sampling and (other) rows are reported in notes.

About the tracking-health checks

They're opinionated rules of thumb built from a few run_report calls, and each result shows what it measured. For example, check_duplicate_transactions counts purchase events grouped by transactionId, and check_traffic_attribution flags Unassigned traffic at 5% or more. They cost the same GA4 quota as the equivalent reports (3–4 report calls).

Troubleshooting

"Not connected yet" (a link and a code like `ABCD-1234`): your AI shows them. Open the link in any browser (it doesn't have to be on this machine), sign in to Tag Pilot, check that the code matches, approve, and allow Google Analytics access, then tell your AI you're done: it retries your question (or calls connection_status). The server keeps checking in the background, so nothing needs restarting. The code is valid for 10 minutes; after that, ask again (or say "connect GA4") for a new one. To connect from a terminal instead (e.g. over SSH), run npx -y @tagpilot/ga4-mcp login: it shows the link, the code in a box and a countdown, and waits until you approve.

"This computer was disconnected from Tag Pilot": the device was revoked on the GA4 MCP page, so its saved credential was removed. Ask again to connect it again.

"Your Google sign-in for GA4 expired or was revoked": the saved sign-in was removed. Ask again and approve again. Google expires refresh tokens after 6 months without use or when you revoke access, and may al