GA4 Analytics MCP

Google Analytics 4 tools for every AI agent -- Claude, Copilot, Cursor, Codex, Gemini, Windsurf, Continue.dev, and Cline. One extension, 8 agents, zero config files to edit.

Install. Authenticate. Ask your AI about your analytics. That's it.

Quick Start

1. Install from the VS Code Marketplace
2. Authenticate -- the setup wizard appears on first launch
3. Ask your AI agent anything about your Google Analytics data

"Show me my top 10 pages by pageviews for the last 7 days"

Prerequisites

You need one of these (the wizard will guide you):

Option A: Application Default Credentials (Easiest)

If you have the gcloud CLI installed, run this in your terminal:

gcloud auth application-default login --scopes=https://www.googleapis.com/auth/analytics.readonly

That's it. The extension will auto-detect your credentials.

Option B: Service Account Key

1. Go to Google Cloud Console > IAM & Admin > Service Accounts
2. Create a service account (or use an existing one)
3. Grant it the Viewer role on your GA4 property
4. Click the service account > Keys > Add Key > Create new key > JSON
5. Save the downloaded .json file somewhere safe
6. In the extension wizard, select "Service Account" and pick the file

Option C: OAuth 2.0 (Browser Login)

This requires a one-time setup in Google Cloud Console:

1. Go to Google Cloud Console
2. Create a project (or select an existing one)
3. Enable the Google Analytics Data API:
   • Go to APIs & Services > Library
   • Search for "Google Analytics Data API"
   • Click Enable
4. Create OAuth credentials:
   • Go to APIs & Services > Credentials
   • Click Create Credentials > OAuth client ID
   • Application type: Desktop app
   • Name: anything (e.g., "GA4 MCP")
   • Click Create
   • Copy the Client ID and Client Secret
5. Configure the OAuth consent screen (if prompted):
   • User type: External (or Internal for Workspace)
   • Add scope: https://www.googleapis.com/auth/analytics.readonly
   • Add yourself as a test user (if External)
6. In the extension wizard, select "OAuth" and paste your Client ID and Secret
7. A browser window opens > sign in with your Google account > authorize

The extension stores your refresh token securely in VS Code's SecretStorage.

Finding Your GA4 Property ID

The wizard asks for your GA4 Property ID. To find it:

1. Go to Google Analytics
2. Click Admin (gear icon, bottom left)
3. In the Property column, click Property Details
4. Your Property ID is the number at the top (e.g., 371242449)

Or just skip it — you can pass property IDs directly in your prompts:

"Run a report on property 371242449 for the last 30 days"

Available Tools

Once set up, your AI agents have access to these tools:

Example Prompts

Show me my top 10 landing pages by sessions for the last 30 days

Compare traffic this week vs last week — sessions and pageviews by day

What are my top traffic sources? Show source/medium with sessions and bounce rate

How many active users do I have right now?

Show me all my GA4 properties

Pro tips:

• You don't need to know the exact API field names — just describe what you want
• The agent will figure out the right dimensions, metrics, and date ranges
• For complex reports, be specific: "sessions by country, filtered to organic traffic, last 90 days, sorted descending"

Supported AI Agents

The extension auto-registers with every AI agent it detects:

You can toggle individual agents on/off in Settings > search ga4Mcp.agents.

Settings

Commands

Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P) and search for:

Troubleshooting

"GA4 MCP: Setup Required" in status bar

Your credentials aren't configured. Click the status bar item or run GA4 MCP: Setup Authentication.

"Permission Denied" errors from Google API

Your credentials don't have access to the GA4 property. Make sure:

• Your Google account has at least Viewer access in GA4 Admin > Property Access Management
• If using a service account, it's been granted access to the property

"Invalid property ID"

Property IDs are numeric (e.g., 371242449). Don't include properties/ prefix or the tracking ID (G-XXXXX).

Server keeps crashing

Run GA4 MCP: View Server Logs to see the error. Common causes:

• Expired credentials > run GA4 MCP: Setup Authentication
• Node.js not found > install Node.js 18+ or the extension will use VS Code's bundled runtime
• Network issues > check your internet connection

Agent not showing GA4 tools

1. Check that the agent is enabled: Settings > search ga4Mcp.agents
2. Run GA4 MCP: Register with AI Agents to re-register
3. Restart the AI agent (e.g., reload Claude Code)
4. Check the output log: GA4 MCP: View Server Logs

Re-authenticating

If your credentials expire or you want to switch auth methods:

1. Run GA4 MCP: Setup Authentication
2. Choose your new auth method
3. The extension will re-register with all agents automatically

Uninstalling cleanly

Before uninstalling the extension:

1. Run GA4 MCP: Remove from All Agents to clean up config files
2. Then uninstall the extension normally

Privacy

This extension:

• Does NOT collect telemetry or send data to third parties
• Communicates only with Google Analytics APIs using your own credentials
• Stores credentials in VS Code's built-in SecretStorage (encrypted, per-user)
• OAuth refresh tokens never leave your machine

Links

• Documentation
• Report an Issue

By Renzo Johnson | Published by mercurial