New Integration: Google Analytics

[AggManik]

Description

Add Google Analytics integration to sync web analytics data including page views, user metrics, sessions, and reporting data into CORE.

Reference Implementations

Existing Integrations (use as templates)

• integrations/google-sheets/ - Similar Google API with OAuth 2.0
• integrations/google-docs/ - Google Workspace integration pattern
• integrations/google-calendar/ - Google OAuth reference

Required Files Structure

integrations/google-analytics/
├── src/
│   ├── index.ts          # Main entry, OAuth spec
│   ├── schedule.ts       # Sync logic
│   ├── utils.ts          # GA Data API utilities
│   ├── account-create.ts # Google OAuth setup
│   └── create-activity.ts # Activity formatting
├── package.json
├── tsup.config.ts
└── README.md

Google Analytics Data API Integration

OAuth Setup

• Use Google OAuth 2.0 (same pattern as other Google integrations)
• Required scopes:
  • https://www.googleapis.com/auth/analytics.readonly - View analytics data
  • https://www.googleapis.com/auth/analytics - Full analytics access
• Base URL: https://analyticsdata.googleapis.com
• API: Google Analytics Data API v1 (GA4)

Key Endpoints

• POST /v1beta/properties/{propertyId}:runReport - Run a standard report
• POST /v1beta/properties/{propertyId}:batchRunReports - Run batch reports
• POST /v1beta/properties/{propertyId}:runPivotReport - Run a pivot report
• POST /v1beta/properties/{propertyId}:runRealtimeReport - Run a realtime report
• GET /v1beta/properties/{propertyId}/metadata - Get available dimensions and metrics
• POST /v1beta/properties/{propertyId}:checkCompatibility - Check metric/dimension compatibility

Events to Track

1. Page Views - Page view counts, unique page views, engagement metrics
2. Sessions - Session data, session duration, bounce rates
3. Users - Active users, new users, returning users
4. Conversions - Goal completions, conversion events
5. Realtime Data - Current active users, realtime events

MCP Tools

GOOGLE_ANALYTICS_ARCHIVE_CUSTOM_DIMENSION

Tool to archive a CustomDimension on a property. Use when you need to remove a custom dimension from active use without permanently deleting it. Archived dimensions cannot be used in new reports.

GOOGLE_ANALYTICS_BATCH_RUN_PIVOT_REPORTS

Tool to return multiple pivot reports in a batch for a GA4 property. Use when you need to fetch multiple pivot table reports with multi-dimensional analysis in a single request.

GOOGLE_ANALYTICS_BATCH_RUN_REPORTS

Tool to return multiple analytics data reports in a batch. Use when you need to fetch multiple reports for one GA4 property in a single request.

GOOGLE_ANALYTICS_CHECK_COMPATIBILITY

Tool to list dimensions and metrics compatible with a GA4 report request. Use when you need to validate compatibility of chosen dimensions or metrics before running a report.

GOOGLE_ANALYTICS_CREATE_AUDIENCE_EXPORT

Tool to create an audience export for Google Analytics. Use when you need to export a snapshot of users in an audience at a specific point in time. This initiates a long-running asynchronous request that returns an operation resource name immediately. The export begins in CREATING state with rowCount=0; the operation must complete before export data is accessible for querying.

GOOGLE_ANALYTICS_CREATE_AUDIENCE_LIST

Tool to create an audience list for later retrieval by initiating a long-running asynchronous request. Use when you need to create a snapshot of users currently in an audience. The method returns quickly with an Operation resource while processing occurs in the background.

GOOGLE_ANALYTICS_CREATE_CUSTOM_DIMENSION

Tool to create a CustomDimension for a Google Analytics property. Use when you need to add a new custom dimension to track specific user properties, event parameters, or eCommerce item parameters.

GOOGLE_ANALYTICS_CREATE_CUSTOM_METRIC

Tool to create a custom metric in Google Analytics. Use when you need to define a new custom metric for tracking specific event parameters.

GOOGLE_ANALYTICS_CREATE_EXPANDED_DATA_SET

Tool to create an expanded data set for a property. Use when you need to combine specific dimensions and metrics into a custom dataset after property creation.

GOOGLE_ANALYTICS_CREATE_RECURRING_AUDIENCE_LIST

Tool to create a recurring audience list that automatically generates new audience lists daily based on the latest data. Use when you need to automate audience list creation and reduce quota token consumption.

GOOGLE_ANALYTICS_CREATE_REPORT_TASK

Tool to create a report task as a long-running asynchronous request for customized Google Analytics event data reports. Use when you need to generate large or complex reports that process asynchronously.

GOOGLE_ANALYTICS_CREATE_ROLLUP_PROPERTY

Tool to create a roll-up property. Use when consolidating multiple GA4 properties into one aggregated view.

GOOGLE_ANALYTICS_GET_ACCOUNT

Tool to retrieve a single Account by its resource name. Use when you need detailed account info after confirming the account resource name (e.g., accounts/100).

GOOGLE_ANALYTICS_GET_ATTRIBUTION_SETTINGS

Tool to retrieve attribution configuration for a Google Analytics property. Use when you need to check attribution models, lookback windows, and conversion export settings.

GOOGLE_ANALYTICS_GET_AUDIENCE

Tool to retrieve a single Audience configuration from a Google Analytics property. Use when you need detailed audience information including membership criteria and filter clauses.

GOOGLE_ANALYTICS_GET_AUDIENCE_EXPORT

Tool to get configuration metadata about a specific audience export. Use when you need to understand an audience export after it has been created or check its status.

GOOGLE_ANALYTICS_GET_AUDIENCE_LIST

Tool to get configuration metadata about a specific audience list. Use after confirming the audience list resource name.

GOOGLE_ANALYTICS_GET_CUSTOM_DIMENSION

Tool to retrieve a single CustomDimension by its resource name. Use when you need detailed information about a specific custom dimension including its display name, scope, and parameter name.

GOOGLE_ANALYTICS_GET_DATA_RETENTION_SETTINGS

Tool to retrieve data retention configuration for a Google Analytics property. Use when you need to check event-level and user-level data retention durations and reset settings.

GOOGLE_ANALYTICS_GET_DATA_SHARING_SETTINGS

Tool to retrieve data sharing configuration for a Google Analytics account. Use when you need to check which data sharing settings are enabled for an account, including sharing with Google support, sales teams, products, and benchmarking.

GOOGLE_ANALYTICS_GET_GOOGLE_SIGNALS_SETTINGS

Tool to retrieve Google Signals configuration settings for a GA4 property. Use when you need to check whether Google Signals is enabled and the consent status for a property.

GOOGLE_ANALYTICS_GET_KEY_EVENT

Tool to retrieve a Key Event. Use after confirming the key event resource name. Read-only; create, update, or delete operations require the Google Analytics UI.

GOOGLE_ANALYTICS_GET_METADATA

Tool to get metadata for dimensions, metrics, and comparisons for a GA4 property. Use to discover available fields before building a report — always derive dimension/metric apiNames from this output rather than hardcoding from GA4 UI labels, which differ. Available fields vary per property; skip validation and downstream report tools like GOOGLE_ANALYTICS_RUN_REPORT return 400 INVALID_ARGUMENT on incompatible or invalid field combinations. Response can contain hundreds of fields; filter to relevant subset before passing to downstream logic.

GOOGLE_ANALYTICS_GET_PROPERTY

Tool to retrieve a single GA4 Property by its resource name. Use when you need detailed property configuration including display name, time zone, currency, and other settings.

GOOGLE_ANALYTICS_GET_PROPERTY_QUOTAS_SNAPSHOT

Tool to retrieve all property quotas organized by category (corePropertyQuota, funnelPropertyQuota, realtimePropertyQuota) for a given GA4 property. Use when you need to check current quota usage. Snapshot data can lag real consumption by several minutes; treat reported values as approximate and avoid scheduling high-volume jobs at full apparent capacity.

GOOGLE_ANALYTICS_GET_RECURRING_AUDIENCE_LIST

Tool to get configuration metadata about a specific recurring audience list. Use when you need to understand a recurring audience list's state after it has been created or to get the resource name of the most recent audience list instance.

GOOGLE_ANALYTICS_GET_REPORT_TASK

Tool to get report metadata about a specific report task. Use after creating a report task to check its processing state or inspect its report definition.

GOOGLE_ANALYTICS_LIST_ACCOUNT_SUMMARIES

Tool to retrieve summaries of all Google Analytics accounts accessible by the caller. Use when you need a high-level overview of accounts and their properties without fetching full account details.

GOOGLE_ANALYTICS_LIST_ACCOUNTS

DEPRECATED: Use ListAccountsV1Beta instead. Tool to list all Accounts accessible by the caller. Use when you need to enumerate all Google Analytics accounts your credentials can access. Empty or partial results may indicate a permissions issue rather than no resources existing. Returned resource names follow the format accounts/{account_id}; use these in subsequent calls.

GOOGLE_ANALYTICS_LIST_ACCOUNTS_V1_BETA

Tool to list all Google Analytics accounts accessible by the caller using v1beta API. Use when you need to enumerate accounts. Note that these accounts might not have GA properties yet. Soft-deleted accounts are excluded by default.

GOOGLE_ANALYTICS_LIST_ADSENSE_LINKS

Tool to list all AdSenseLinks on a property. Use when you need to fetch all AdSense links for a given Google Analytics property.

GOOGLE_ANALYTICS_LIST_AUDIENCE_EXPORTS

Tool to list all audience exports for a property. Use when you need to find and reuse existing audience exports rather than creating new ones.

GOOGLE_ANALYTICS_LIST_AUDIENCE_LISTS

Tool to list all audience lists for a specified property to help find and reuse existing lists. Use when you need to retrieve a property's configured audience lists after confirming the property ID.

GOOGLE_ANALYTICS_LIST_AUDIENCES

Tool to list Audiences on a property. Use when you need to retrieve audience configurations for a Google Analytics property. Audiences created before 2020 may not be supported.

GOOGLE_ANALYTICS_LIST_BIGQUERY_LINKS

Tool to list BigQuery Links on a property. Use when you need to retrieve BigQuery link resources associated with a Google Analytics property. Results support pagination for large datasets.

GOOGLE_ANALYTICS_LIST_CALCULATED_METRICS

Tool to list CalculatedMetrics on a property. Use when you need to retrieve all calculated metrics configured for a given property.

GOOGLE_ANALYTICS_LIST_CHANNEL_GROUPS

Tool to list ChannelGroups on a property. Use when you need to retrieve channel groups that categorize traffic sources in Analytics reports.

GOOGLE_ANALYTICS_LIST_CONVERSION_EVENTS

Tool to list conversion events on a property. Use when you need to retrieve conversion events configured for a given property.

GOOGLE_ANALYTICS_LIST_CUSTOM_DIMENSIONS

Tool to list CustomDimensions on a property. Use when you need to retrieve custom dimensions configured for a given property.

GOOGLE_ANALYTICS_LIST_CUSTOM_METRICS

Tool to list CustomMetrics on a property. Use when you need to retrieve all custom metrics configured for a given property.

GOOGLE_ANALYTICS_LIST_DATA_STREAMS

Tool to list DataStreams on a property. Use when you need to retrieve data stream configurations for a Google Analytics property.

GOOGLE_ANALYTICS_LIST_DV360_AD_LINKS

Tool to list Display & Video 360 advertiser links on a property. Use when you need to retrieve DisplayVideo360AdvertiserLink resources associated with a Google Analytics property. Results support pagination for large datasets.

GOOGLE_ANALYTICS_LIST_DV360_LINK_PROPOSALS

Tool to list DisplayVideo360AdvertiserLinkProposals on a property. Use when you need to retrieve Display & Video 360 advertiser link proposals associated with a Google Analytics property. Results support pagination for large datasets.

GOOGLE_ANALYTICS_LIST_EVENT_CREATE_RULES

Tool to list EventCreateRules configured on a web data stream. Use when you need to retrieve event create rules for a specific GA4 property data stream.

GOOGLE_ANALYTICS_LIST_EXPANDED_DATA_SETS

Tool to list ExpandedDataSets on a property. Use when you need to retrieve expanded data set configurations for a Google Analytics 360 property.

GOOGLE_ANALYTICS_LIST_FIREBASE_LINKS

Tool to list FirebaseLinks on a property. Use when you need to retrieve Firebase connections associated with a Google Analytics property. Each property can have at most one FirebaseLink.

GOOGLE_ANALYTICS_LIST_GOOGLE_ADS_LINKS

Tool to list GoogleAdsLinks on a property. Use when you need to retrieve Google Ads account links configured for a Google Analytics property. Supports pagination for large result sets.

GOOGLE_ANALYTICS_LIST_KEY_EVENTS

Tool to list Key Events. Use when you need to retrieve all key event definitions for a given property. Key events are read-only via API; creation, updates, and deletion require the Google Analytics UI. An empty results list means no key events are configured, not a failure. Do not infer key-event status from report data (e.g., eventCount); use this tool to confirm.

GOOGLE_ANALYTICS_LIST_MEASUREMENT_PROTOCOL_SECRETS

Tool to list MeasurementProtocolSecrets under a data stream. Use when you need to retrieve measurement protocol secrets for server-side event tracking.

GOOGLE_ANALYTICS_LIST_PROPERTIES

DEPRECATED: Use ListPropertiesV1Beta instead. Tool to list GA4 properties under a specific account. Use after obtaining an account ID; supports pagination and including soft-deleted properties. Results may include legacy Universal Analytics properties; verify property type before use.

GOOGLE_ANALYTICS_LIST_PROPERTIES_FILTERED

Tool to list GA4 properties based on filter criteria. Use when you need to find properties under a specific parent account or with specific firebase projects. Supports pagination and including soft-deleted properties.

GOOGLE_ANALYTICS_LIST_RECURRING_AUDIENCE_LISTS

Tool to list all recurring audience lists for a GA4 property. Use when you need to find and reuse existing recurring audience lists.

GOOGLE_ANALYTICS_LIST_REPORT_TASKS

Tool to list all report tasks for a Google Analytics property. Use when you need to retrieve report task definitions and their execution status.

GOOGLE_ANALYTICS_LIST_REPORTING_DATA_ANNOTATIONS

Tool to list all Reporting Data Annotations for a specific property. Use when you need to retrieve annotations that document important events or periods in GA4 reporting data.

GOOGLE_ANALYTICS_LIST_SEARCH_ADS360_LINKS

Tool to list all SearchAds360Links on a property. Use when you need to retrieve all Search Ads 360 links for a given Google Analytics property. Supports pagination for large result sets.

GOOGLE_ANALYTICS_LIST_SK_AD_NETWORK_CONVERSION_VALUE_SCHEMAS

Tool to list SKAdNetworkConversionValueSchema configurations for an iOS data stream. Use when you need to retrieve conversion value schemas for iOS app tracking. Maximum one schema per property is supported.

GOOGLE_ANALYTICS_LIST_SUBPROPERTY_EVENT_FILTERS

Tool to list all subproperty event filters on a property. Use when you need to retrieve event filters that route events to subproperties.

GOOGLE_ANALYTICS_LIST_SUBPROPERTY_SYNC_CONFIGS

Tool to list SubpropertySyncConfig resources for managing subproperty synchronization configurations. Use when you need to fetch subproperty sync configs for a GA4 property.

GOOGLE_ANALYTICS_PROVISION_ACCOUNT_TICKET

Tool to request a ticket for creating a Google Analytics account. Use when you need to initiate the account creation flow that requires user acceptance of Terms of Service.

GOOGLE_ANALYTICS_QUERY_AUDIENCE_EXPORT

Tool to query a completed audience export. Use when you need to fetch user rows with pagination.

GOOGLE_ANALYTICS_QUERY_AUDIENCE_LIST

Tool to query an audience list. Use when you need to retrieve user rows from a GA4 audience list with pagination.

GOOGLE_ANALYTICS_QUERY_REPORT_TASK

Tool to retrieve a report task's content. Use this after creating a report task with CreateReportTask and confirming it is in ACTIVE state. This method returns an error if the report task's state is not ACTIVE.

GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT

Tool to run a GA4 funnel report. Use when you need a customized funnel analysis report for a given property. Funnel step sequence is determined by step attributes in the response, not row order.

GOOGLE_ANALYTICS_RUN_PIVOT_REPORT

Tool to run a customized pivot report of Google Analytics event data. Use when you need a pivot table view with advanced segmentation and multi-dimensional analysis of GA4 data.

GOOGLE_ANALYTICS_RUN_REALTIME_REPORT

Tool to run a customized realtime report of Google Analytics event data. Use when you need realtime data (last 30-60 minutes) with dimensions and metrics for a GA4 property.

GOOGLE_ANALYTICS_RUN_REPORT

Tool to run a customized GA4 data report. Use when you need event data after specifying dimensions, metrics, and date ranges. IMPORTANT - DIMENSION/METRIC COMPATIBILITY: The Google Analytics Data API has strict compatibility rules between dimensions and metrics. Not all combinations are valid. If you receive a 400 error with a message about incompatible dimensions/metrics, use the GOOGLE_ANALYTICS_CHECK_COMPATIBILITY action first to validate your dimension/metric combinations before running reports. Common incompatibilities include: - Demographic dimensions (userAgeBracket, userGender) with session-scoped dimensions/filters (sessionCampaignName, sessionSource) - Certain user-scoped dimensions with event-scoped metrics For complex queries, consider starting with simpler dimension/metric combinations or use CHECK_COMPATIBILITY to pre-validate your request.

GOOGLE_ANALYTICS_SEND_EVENTS

Tool to send event data to Google Analytics 4 using the Measurement Protocol. Use when you need to track server-side events that supplement client-side gtag.js or Firebase tracking. The Measurement Protocol allows sending event data directly to GA4 from servers, applications, or other devices. Events are processed asynchronously and typically appear in reports within 24-48 hours. For validation, use the validation server endpoint first (mp/collect/validate).

GOOGLE_ANALYTICS_UPDATE_PROPERTY

Tool to update an existing GA4 Property. Use when you need to modify property settings such as display name, time zone, currency code, or industry category.

GOOGLE_ANALYTICS_VALIDATE_EVENTS

Tool to validate Measurement Protocol events before sending them to production. Use when you need to verify event structure and parameters are correct before sending real data.

Implementation Tasks

• Set up basic integration structure following integrations/google-sheets/src/index.ts pattern
• Implement Google OAuth 2.0 flow in account-create.ts (reuse existing Google OAuth pattern)
• Create API utilities in utils.ts with GA Data API v1 client
• Implement sync logic in schedule.ts for reports, metrics, dimensions
• Convert GA analytics data to CORE activity format
• Add error handling and rate limiting
• Create integration documentation
• Add to integrations/README.md

Technical Notes

• This is the GA4 Data API (v1), replacing the deprecated Universal Analytics API
• Events appear in realtime reports within seconds of being sent
• getMetadata returns available dimensions/metrics including custom ones for a property
• Can reuse Google OAuth flow from existing integrations
• Client libraries available for Java, PHP, Python, Node.js, .NET, Ruby, Go
• Reports are request-based (POST) rather than resource-based (GET)
• Supports date range queries for historical data sync
• Quota limits apply per property and per project

Resources

• Google Analytics Data API v1 Overview
• GA Data API REST Reference
• GA Data API Quickstart
• Google Analytics Help

Labels

enhancement, integration, new-feature

[rupert61622-blip]

Alongside GA, it might be worth considering integrations with privacy-focused analytics too. A lot of users are moving away from Google Analytics for GDPR/privacy reasons:

• Plausible - lightweight, open source, no cookies needed. Simple API for pulling stats.
• Umami - self-hostable, clean dashboard, good API support.
• PostHog - more full-featured (product analytics + session replay), also self-hostable.

All three have REST APIs that would be straightforward to integrate. Plausible and Umami in particular have very clean data models.

There's a comparison of analytics alternatives at indiestack.fly.dev/alternatives/google-analytics if it helps scope which ones to prioritize.

[AggManik]

Hey @rupert61622-blip i'll create good-first issues for these 3 as well.