Google Analytics MCP Server

A Model Context Protocol (MCP) server that provides seamless access to Google Analytics 4 data through standard MCP interfaces. This tool allows LLM applications to easily query and analyze Google Analytics data without directly dealing with the complexities of the Google Analytics Data API.

✨ Features

• 🔐 Dual Authentication: Support both Service Account and OAuth2 User Authorization
• Real-time Data Access: Get real-time analytics data for current active users and activity
• Custom Reports: Create comprehensive reports with custom dimensions and metrics
• Quick Insights: Predefined analytics insights for common use cases
• Metadata Discovery: Get available dimensions and metrics for your Google Analytics property
• 🔄 Auto Token Refresh: Automatically refreshes expired OAuth2 access tokens
• Smart Error Handling: Detailed error messages with actionable solutions for permission issues
• Standard MCP Interface: Works with any MCP-compatible client

Installation

npm install @toolsdk.ai/google-analytics-mcp

Prerequisites

• Node.js >= 18.0.0
• Google Analytics 4 property
• Either:
  • Service Account credentials (default), OR
  • OAuth2 tokens from a user authorization flow

🔐 Authentication Modes

This MCP server supports two authentication modes, controlled by the GOOGLE_AUTH_MODE environment variable:

| Mode | Value | Description | |------|-------|-------------| | Service Account | service_account (default) | Use a GCP service account JSON key | | OAuth2 | oauth2 | Use user-authorized OAuth2 tokens |

Mode 1: Service Account (Default)

Use this mode for server-to-server authentication without user interaction.

Setup Steps

1. Create a Service Account in Google Cloud Console
2. Download the JSON key file
3. Grant access to your GA4 property:
   • Go to Google Analytics → Admin → Property Access Management
   • Add the service account email (e.g., [email protected]) with Viewer access

Environment Variables

# Optional: defaults to 'service_account'
GOOGLE_AUTH_MODE=service_account

# Option 1: Direct JSON string
GOOGLE_CREDENTIALS='{"type":"service_account","project_id":"...","private_key":"...","client_email":"..."}'

# Option 2: Path to JSON file
GOOGLE_CREDENTIALS_PATH=/path/to/service-account.json

Claude Desktop Configuration

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "npx",
      "args": ["-y", "@toolsdk.ai/google-analytics-mcp"],
      "env": {
        "GOOGLE_AUTH_MODE": "service_account",
        "GOOGLE_CREDENTIALS_PATH": "/path/to/service-account.json"
      }
    }
  }
}

Mode 2: OAuth2 User Authorization

Use this mode to access GA data on behalf of a user with their own permissions.

Advantages

• ✅ Access the user's own GA properties without service account setup
• ✅ No need to add service accounts to GA property permissions
• ✅ Works with the user's existing Google account permissions

⚠️ Important: This MCP server does NOT include the OAuth2 authorization flow itself. You need to implement the OAuth2 consent flow separately to obtain the tokens.

1. Implement OAuth2 Authorization Flow (Your Responsibility)

You need to implement the OAuth2 authorization flow using libraries like:

• googleapis (Node.js)
• google-auth-library (Node.js)

Required OAuth2 scopes:

https://www.googleapis.com/auth/analytics.readonly

Example OAuth2 flow (simplified):

import { google } from 'googleapis';

const oauth2Client = new google.auth.OAuth2(
  CLIENT_ID,
  CLIENT_SECRET,
  REDIRECT_URI
);

// Generate auth URL and redirect user
const authUrl = oauth2Client.generateAuthUrl({
  access_type: 'offline',  // Important: to get refresh_token
  scope: ['https://www.googleapis.com/auth/analytics.readonly']
});

// After user consent, exchange code for tokens
const { tokens } = await oauth2Client.getToken(code);

// Save tokens to tokens.json
fs.writeFileSync('tokens.json', JSON.stringify(tokens, null, 2));

2. tokens.json Format

After completing the OAuth2 flow, save the tokens in a tokens.json file:

{
  "access_token": "ya29.a0AWY7CknXXX...",
  "refresh_token": "1//0eXXX...",
  "scope": "https://www.googleapis.com/auth/analytics.readonly",
  "token_type": "Bearer",
  "expiry_date": 1234567890000
}

| Field | Description | Required | |-------|-------------|----------| | access_token | The OAuth2 access token | ✅ Yes | | refresh_token | The refresh token (for auto-renewal) | ⚠️ Recommended | | scope | Authorized scopes | Optional | | token_type | Token type (usually "Bearer") | Optional | | expiry_date | Token expiration timestamp (ms) | ⚠️ Recommended |

3. Token Loading Priority

The MCP server loads OAuth2 tokens in the following order:

1. Direct JSON string via GOOGLE_OAUTH2_TOKENS environment variable
2. Path specified by GOOGLE_OAUTH2_TOKEN_PATH environment variable
3. {current working directory}/tokens.json
4. {current working directory}/../tokens.json
5. {src directory}/../../tokens.json

4. Environment Variables (OAuth2 Mode)

GOOGLE_AUTH_MODE=oauth2

# Option 1: Direct JSON string
GOOGLE_OAUTH2_TOKENS='{"access_token":"ya29...","refresh_token":"1//0e...","expiry_date":1234567890000}'

# Option 2: Path to tokens.json
GOOGLE_OAUTH2_TOKEN_PATH=/path/to/your/tokens.json

# Optional: For automatic token refresh
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret

Claude Desktop Configuration (OAuth2)

{
  "mcpServers": {
    "google-analytics-mcp": {
      "command": "npx",
      "args": ["-y", "@toolsdk.ai/google-analytics-mcp"],
      "env": {
        "GOOGLE_AUTH_MODE": "oauth2",
        "GOOGLE_OAUTH2_TOKEN_PATH": "/path/to/your/tokens.json",
        "GOOGLE_CLIENT_ID": "your-client-id (optional)",
        "GOOGLE_CLIENT_SECRET": "your-client-secret (optional)"
      }
    }
  }
}

⚠️ Token Lifecycle Management (OAuth2 Mode)

Access Token Expiration

• Google OAuth2 access tokens typically expire after 1 hour
• The MCP server will automatically attempt to refresh tokens if refresh_token is provided

Automatic Token Refresh

When configured with GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, the server will:

1. Detect when the access token is expired
2. Use the refresh_token to obtain a new access_token
3. Automatically save the new tokens to tokens.json

Refresh Token Considerations

⚠️ Important Notes about Refresh Tokens:

1. Refresh tokens can expire or be revoked:

   • If the user revokes access in their Google Account settings
   • If the refresh token is unused for 6 months (for non-verified apps)
   • If you've exceeded the limit of 100 refresh tokens per user per client

2. Getting a refresh token:

   • You only get a refresh_token on the first authorization
   • Use access_type: 'offline' in your auth URL
   • Use prompt: 'consent' to force re-consent and get a new refresh token

3. Recommended practices:

   • Always request access_type: 'offline' during OAuth2 flow
   • Store and protect the refresh_token securely
   • Implement re-authorization flow for when refresh tokens become invalid
   • Monitor for invalid_grant errors which indicate the refresh token is no longer valid

Available Tools

analytics_report

Get comprehensive Google Analytics data with custom dimensions and metrics. Can create any type of report.

Parameters:

• propertyId (string, required): Google Analytics property ID
• startDate (string, required): Start date (YYYY-MM-DD)
• endDate (string, required): End date (YYYY-MM-DD)
• dimensions (array, optional): Dimensions to query
• metrics (array, required): Metrics to query
• dimensionFilter (object, optional): Filter by dimension values
• metricFilter (object, optional): Filter by metric values
• orderBy (object, optional): Sort results by dimension or metric
• limit (number, optional): Limit number of results (default: 100)

realtime_data

Get real-time analytics data for current active users and activity.

Parameters:

• propertyId (string, required): Google Analytics property ID
• dimensions (array, optional): Dimensions for real-time data
• metrics (array, optional): Real-time metrics (default: ['activeUsers'])
• limit (number, optional): Limit number of results (default: 50)

quick_insights

Get predefined analytics insights for common use cases.

Parameters:

• propertyId (string, required): Google Analytics property ID
• startDate (string, required): Start date (YYYY-MM-DD)
• endDate (string, required): End date (YYYY-MM-DD)
• reportType (string, required): Type of quick insight report (overview, top_pages, traffic_sources, etc.)
• limit (number, optional): Limit number of results (default: 20)

get_metadata

Get available dimensions and metrics for Google Analytics property.

Parameters:

• propertyId (string, required): Google Analytics property ID
• type (string, optional): Type of metadata to retrieve (dimensions, metrics, both)

search_metadata

Search for specific dimensions or metrics by name or category.

Parameters:

• propertyId (string, required): Google Analytics property ID
• query (string, required): Search term to find dimensions/metrics
• type (string, optional): Type of metadata to search (dimensions, metrics, both)
• category (string, optional): Filter by category

Error Handling

The server provides detailed error messages with actionable solutions based on the authentication mode:

Service Account Mode:

• Permission errors will prompt you to add the service account email to GA property access

OAuth2 Mode:

• Permission errors will suggest re-authorization
• Token errors will indicate refresh or re-authorization needs

Environment Variables Summary

| Variable | Mode | Description | |----------|------|-------------| | GOOGLE_AUTH_MODE | Both | service_account (default) or oauth2 | | GOOGLE_CREDENTIALS | Service Account | JSON string of service account key | | GOOGLE_CREDENTIALS_PATH | Service Account | Path to service account JSON file | | GOOGLE_OAUTH2_TOKENS | OAuth2 | JSON string of OAuth2 tokens | | GOOGLE_OAUTH2_TOKEN_PATH | OAuth2 | Path to tokens.json | | GOOGLE_CLIENT_ID | OAuth2 | Client ID for token refresh | | GOOGLE_CLIENT_SECRET | OAuth2 | Client secret for token refresh |

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT