Getting Started with GA4 MCP

Setup takes about two minutes and there's no key to copy: install the server, ask a GA4 question, and approve once in your browser.

1. Install it in your AI client

Everything except the Claude Desktop extension runs the npm package with npx, so it needs Node.js 18 or newer (node --version). The install buttons are on the GA4 MCP page in Tag Pilot; new to Tag Pilot? Create a free account, or skip this and let the first question take you there.

The server is also listed in the official MCP Registry as io.github.tagpilot/ga4-mcp, for clients that install from it.

Claude Desktop

1. Download tagpilot-ga4-mcp.mcpb (also on the GA4 MCP page: Download for Claude Desktop).
2. Double-click it, or drag it into Settings → Extensions.
3. Click Install and make sure the extension is enabled. 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? Open Settings → Developer → Edit Config, add this to claude_desktop_config.json and restart Claude:

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

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

Claude Code

Run in a terminal:

claude mcp add ga4 -- 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. Then start a new Claude Code session, or reconnect with /mcp.

Cursor

Click Add to Cursor on the GA4 MCP page, or add it by hand to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

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

VS Code

Click Install in VS Code on the GA4 MCP page, or add it by hand to .vscode/mcp.json in your workspace. VS Code uses servers instead of mcpServers:

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

Gemini CLI

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

Other MCP clients

Any client that runs local (stdio) MCP servers works, for example Windsurf (now Devin Desktop) under Settings → MCP, or Zed: the command is npx and the arguments are -y @tagpilot/ga4-mcp. Most clients take the same mcpServers JSON as Cursor.

2. Connect on the first question

Start a new session in your AI client (MCP servers load when a session starts), then ask something, for example "Which GA4 properties do I have?", or just say "connect GA4". Your AI client shows a clickable link and a code like ABCD-1234; clients that support it also offer to open the link for you.

1. Open the link: it goes to app.tagpilot.io/connect. Use any browser, on any device, even your phone.
2. Log in to your free Tag Pilot account, or create one.
3. Check that the code and computer match what your AI client shows, and click Approve and sign in with Google. Only approve a code you just started yourself.
4. Google's sign-in opens. Choose the Google account that can see your GA4 properties and allow See and download your Google Analytics data.
5. The page says Connected. Close the tab and tell your AI client you're done: it checks the connection and answers your original question.

You don't need a terminal. Your AI client uses two helper tools for this: connect (starts connecting and returns the link and code) and connection_status (waits up to 25 seconds for your approval, then says whether you're connected). Any data question asked before you're connected returns the same link and code. The code is valid for 10 minutes.

Because nothing has to reach your computer, this also works over SSH, in containers, in WSL and on remote dev boxes. Prefer a terminal? npx -y @tagpilot/ga4-mcp login shows the link and a boxed code with a countdown, and waits until you approve.

Once connected, the computer shows up under Connected devices on the GA4 MCP page, labelled with the AI client and computer name, for example GA4 MCP · Cursor on work-laptop. You connect once per computer; Google tokens refresh by themselves after that.

"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 Continue (or Go to … (unsafe)). You still grant only read-only access to Google Analytics; the next screen lists exactly what is requested. While verification is pending, Tag Pilot GA4 MCP is in a limited beta: see Troubleshooting if Google says the app is blocked.

3. Check the setup

npx -y @tagpilot/ga4-mcp status

version: 0.3.0
api url: https://api.tagpilot.io
device: connected (Tag Pilot key tpk_abcd…; manage it on https://app.tagpilot.io/ga4-mcp)
token file: /home/you/.config/tagpilot/ga4-mcp/device.json
google: signed in (access token valid until 2026-10-28T13:05:11.000Z)

Headless and CI: an API key instead

Where nobody can approve in a browser, use a key instead of connecting:

1. On the GA4 MCP page, under Create a key manually, click Create GA4 MCP key and give it a label, for example CI runner. Copy the key: it starts with tpk_ and is shown only once.

2. Set it as TAGPILOT_API_KEY in the server's environment:

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

With a key, the Tag Pilot connect step is skipped and only the Google sign-in link is shown, the first time. You still have to approve Google once, in any browser; TAGPILOT_API_KEY=tpk_your_key npx -y @tagpilot/ga4-mcp login does it from a terminal. The key also appears under Connected devices, where you can revoke it.

Commands

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

With TAGPILOT_API_KEY set, status, login and logout work on that key's sign-in only. logout deletes the credentials on your computer; to also revoke the device in Tag Pilot, use Revoke under Connected devices.

Settings

Nothing is required. All settings are optional environment variables, set in the server's env in your AI client's config:

Next steps

• Browse the tools and example prompts.
• Something not working? See Troubleshooting.
• Want Google Search Console too? See the Search Console MCP.