Getting Started with GA4 MCP

Setup takes about two minutes: create a key, add the server to your AI client, then sign in with Google on the first question. You need Node.js 18 or newer (node --version).

1. Create a key

1. Sign up or log in at app.tagpilot.io and open GA4 MCP in the sidebar.
2. Click Create GA4 MCP key and give it a label, for example Work laptop.
3. Copy the key. It starts with tpk_ and is shown only once. The install snippets on the page already include it.

Create one key per computer, so you can revoke each on its own. A GA4 MCP key only lets the package sign in to Google: it can't read your other Tag Pilot data, and keys made elsewhere in the app don't work for the GA4 MCP.

2. Add it to your AI client

In the snippets below, replace tpk_your_key with your key.

Claude Code

Run in a terminal:

claude mcp add ga4 --env TAGPILOT_API_KEY=tpk_your_key -- npx -y @tagpilot/ga4-mcp

This adds it to the current project. Add --scope user after claude mcp add to use it in every project. Check it with /mcp inside Claude Code.

Claude Desktop

Open Settings → Developer → Edit Config, add this to claude_desktop_config.json, and restart Claude:

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

If the file already has an mcpServers block, add the ga4 entry inside it.

Cursor

Add the same JSON to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

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

Other MCP clients

Any client that runs local (stdio) MCP servers works. It needs the same three things: the command npx, the arguments -y @tagpilot/ga4-mcp, and TAGPILOT_API_KEY in the environment.

Gemini CLI can also add it for you:

gemini mcp add -e TAGPILOT_API_KEY=tpk_your_key ga4 npx -y @tagpilot/ga4-mcp

VS Code (.vscode/mcp.json):

{
  "servers": {
    "ga4": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tagpilot/ga4-mcp"],
      "env": { "TAGPILOT_API_KEY": "tpk_your_key" }
    }
  }
}

Client config formats change from time to time; if one of these doesn't load, check the client's own MCP documentation.

3. Sign in with Google

Ask something, for example "Which GA4 properties do I have?"

1. A browser window opens on Google's sign-in page. Choose the Google account that can see your GA4 properties.
2. Approve See and download your Google Analytics data.
3. The page says GA4 is connected. Close the tab and go back to your AI client.
4. If the AI client already answered "Waiting for you to sign in with Google", ask again.

The tool waits up to 45 seconds for you to finish signing in, because many clients give up on a tool call after a minute. The sign-in itself stays open for 10 minutes, so take your time and repeat the question afterwards. No browser window? The answer includes the sign-in link: open it yourself.

"Google hasn't verified this app"

Google is still reviewing Tag Pilot's app, so you may see this warning before the consent screen. To continue, click Advanced, then Go to … (unsafe). You still grant only read-only access to Google Analytics; the next screen lists exactly what is requested.

You sign in once per key. Google tokens refresh by themselves after that.

4. Check the setup

status shows the API URL and every Google sign-in saved on this computer, with whether it's still valid:

npx -y @tagpilot/ga4-mcp status

version: 0.1.1
mode: broker
api url: https://api.tagpilot.io
api key: not set in this shell (normal: your MCP client passes it to the server; set TAGPILOT_API_KEY to check one key)
saved sign-ins: 1
  /home/you/.config/tagpilot/ga4-mcp/3f2a9c1e7b4d5a60.json: signed in (access token valid until 2026-10-27T13:05:11.000Z)

"api key: not set" is expected: the key lives in your AI client's config, which passes it to the server. To check one key's sign-in only, put the key in front: TAGPILOT_API_KEY=tpk_your_key npx -y @tagpilot/ga4-mcp status. On Windows PowerShell, set the variable first: $env:TAGPILOT_API_KEY="tpk_your_key"; npx -y @tagpilot/ga4-mcp status.

Commands

The same package has a few helper commands. Without a command, it runs the MCP server (that's what your AI client starts).

Each key has its own saved sign-in, so login needs the key, and status and logout cover one key when you give it and all of them when you don't. You rarely need login: the first GA4 question in your AI client signs you in.

This applies from version 0.1.1. With 0.1.0, status, logout and login work only with TAGPILOT_API_KEY=tpk_your_key in front. npx -y picks up the latest version by itself.

Settings

All settings are environment variables. Set them in the same env block as the key.

Next steps

• Browse the tools and example prompts.
• Something not working? See Troubleshooting.