Google Analytics MCP Server

GA-MCP (Google Analytics Management Control Panel) is a lightweight Node.js package that provides developers with a structured interface to interact with Google Analytics APIs. It simplifies common GA tasks like querying analytics reports, managing properties, audiences, and more—making it ideal for data analysts, developers, and marketing teams looking to automate reporting and analytics workflows. MCP standard.

Features

Fetch and analyze GA performance data (sessions, users, pageviews, conversions)
Manage properties, data streams, and conversion events
Query custom dimensions and metrics
Access account hierarchies and property configurations
Export data for dashboards or further analysis
OAuth2 authentication with access and refresh tokens
Lightweight, secure, and highly configurable

MCP Tools

get_reports: Get analytics reports data for specified metrics and dimensions
list_accounts: List all Google Analytics accounts
list_properties: List properties for a Google Analytics account
list_data_streams: List data streams for a property
list_custom_dimensions: List custom dimensions for a property
list_custom_metrics: List custom metrics for a property
list_conversion_events: List conversion events for a property

Getting Started

Prerequisites

Node.js v18 or later
Google OAuth2 credentials (Client ID and Client Secret)
Valid Google Analytics access and refresh tokens

Authentication Setup

Create OAuth2 Credentials:
- Go to the Google Cloud Console
- Create or select a project
- Enable the Google Analytics API
- Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
- Configure the consent screen and choose the appropriate application type:
  
  Option A: Web Application (Recommended)
  - Select "Web application"
  - Add http://localhost:3000/auth/callback to "Authorized redirect URIs"
  Option B: Desktop Application
  - Select "Desktop application"
  - No redirect URI configuration needed (uses out-of-band flow)
Generate Access and Refresh Tokens:
- Use the included helper script: npm run oauth-helper
- Or use Google OAuth2 Playground with your client credentials
- Or implement your own OAuth2 flow

Quick Setup Workflow

# 1. Set up environment file
npm run setup-env

# 2. Edit .env with your OAuth2 Client ID and Secret (from step 1 above)

# 3. Generate tokens
npm run oauth-helper

# 4. Copy the generated tokens to your .env file

# 5. Build and start
npm run build
node dist/index.js

Installation

Clone this repository and install dependencies:

pnpm install
# or
npm install

Build

pnpm build
# or
npm run build

Configuration Environment Variables

Option 1: Using .env file (Recommended)

Set up your environment file:

npm run setup-env
# This creates .env from the template
# Edit .env file with your actual credentials

Option 2: Using export commands

Set the following environment variables:

export GOOGLE_CLIENT_ID=your_oauth2_client_id
export GOOGLE_CLIENT_SECRET=your_oauth2_client_secret
export GOOGLE_ACCESS_TOKEN=your_access_token
export GOOGLE_REFRESH_TOKEN=your_refresh_token

Start

Start the MCP server:

node dist/index.js

Integrate with Cursor

To use this MCP server with Cursor, add a .cursor/mcp.json file to your project root:

{
  "mcpServers": {
    "ga-mcp": {
      "command": "npx",
      "args": ["-y", "ga-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_oauth2_client_id",
        "GOOGLE_CLIENT_SECRET": "your_oauth2_client_secret",
        "GOOGLE_ACCESS_TOKEN": "your_access_token",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Integrate with VSCode

To use this MCP server with VSCode, add a .vscode/mcp.json file to your project root:

{
  "servers": {
    "ga-mcp": {
      "command": "npx",
      "args": ["-y", "ga-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_oauth2_client_id",
        "GOOGLE_CLIENT_SECRET": "your_oauth2_client_secret",
        "GOOGLE_ACCESS_TOKEN": "your_access_token",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

This configuration enables VSCode to recognize and manage the Google Analytics MCP server automatically.

This configuration enables Cursor to recognize and manage the Google Analytics MCP server automatically.

Token Refresh

The MCP server automatically handles token refresh using the provided refresh token. If the access token expires, it will be automatically refreshed during API calls.

Troubleshooting

"The redirect URI... can only be used by a Client ID for native application"

This error occurs when you have a Web application OAuth client but are using the out-of-band redirect URI. Solutions:

Solution 1: Use Web Application (Recommended)

In Google Cloud Console, edit your OAuth client
Add http://localhost:3000/auth/callback to "Authorized redirect URIs"
Keep GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback in your .env file

Solution 2: Switch to Desktop Application

Create a new OAuth client and select "Desktop application"
Set GOOGLE_REDIRECT_URI=urn:ietf:wg:oauth:2.0:oob in your .env file

About AST Consulting

AST Consulting is a premier digital consulting firm specializing in FinOps, cloud optimization, AI/ML solutions, digital transformation, and performance marketing. With over 100 years of combined leadership experience and a portfolio impacting 50M+ businesses and 500M+ users, AST delivers measurable outcomes by blending strategic vision with deep technical expertise.

We developed ga-mcp as part of our commitment to empower marketers, analysts, and digital teams with tools that drive efficiency, transparency, and actionable insights. Whether optimizing cloud spend or automating analytics intelligence pipelines, AST builds solutions that scale.

👉 Visit us at www.astconsulting.in

ga-mcp