Ga4 Viz

An MCP server that enables interactive Google Analytics 4 visualizations inside Claude conversations.

Features

• OAuth Authentication: Secure browser-based OAuth 2.0 PKCE flow
• Ad-hoc Queries: Run custom GA4 queries with dimension/metric selection
• Interactive Charts: Line, bar, pie charts and data tables using Chart.js
• Dark Mode: Automatic theme adaptation

Setup

Prerequisites

1. A Google Cloud project with the Google Analytics Data API enabled
2. OAuth 2.0 credentials configured for desktop application
3. A GA4 property ID

Google Cloud Configuration

1. Go to Google Cloud Console
2. Enable the Google Analytics Data API
3. Create OAuth 2.0 credentials:
   • Application type: Desktop app
   • Add http://127.0.0.1:9876/callback as an authorized redirect URI
4. Note your Client ID and Client Secret

Installation

# Clone and install dependencies
cd mcp-ga4-viz
pnpm install

# Build both packages
pnpm build

Configuration

Create a .env file in the project root:

GA4_PROPERTY_ID=123456789
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxx

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ga4-viz": {
      "command": "node",
      "args": ["/path/to/mcp-ga4-viz/packages/server/dist/index.js"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_CLIENT_ID": "xxx.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "xxx"
      }
    }
  }
}

Usage

Authentication

First, authenticate with Google Analytics:

"Authenticate with Google Analytics"

This opens a browser window for OAuth consent. After authenticating, you can run queries.

Running Queries

Example queries:

"Show me sessions by country for the last 7 days as a bar chart"

"Get pageviews and users by date for the last 30 days as a line chart"

"Show top 10 landing pages by sessions"

Available Tools

Tool	Description
ga4_authenticate	Manage OAuth authentication (login/status/logout)
ga4_query	Run ad-hoc GA4 queries with visualization

Common Dimensions

• date, country, city
• deviceCategory, browser, operatingSystem
• sessionSource, sessionMedium, sessionCampaignName
• pagePath, pageTitle, landingPage
• eventName

Common Metrics

• sessions, totalUsers, newUsers, activeUsers
• screenPageViews, eventCount, conversions
• engagedSessions, engagementRate
• averageSessionDuration, bounceRate

Development

# Run server in development mode
cd packages/server
pnpm dev

# Run UI in development mode
cd packages/ui-chart
pnpm dev

Architecture

mcp-ga4-viz/
├── packages/
│   ├── server/           # MCP server + GA4 API + OAuth
│   │   ├── src/
│   │   │   ├── auth/     # OAuth PKCE flow, token management
│   │   │   ├── ga4/      # GA4 Data API client
│   │   │   └── tools/    # MCP tool implementations
│   │   └── dist/ui/      # Built UI assets
│   └── ui-chart/         # Preact + Chart.js visualization
└── pnpm-workspace.yaml

License

MIT