Merge pull request #4239 from Ttian18/feat/tina-google-analytics-tool

[Integration]: Google Analytics - Website Traffic & Marketing Performance #3727

Author: bryanadenhq

tools/pyproject.toml

@@ -31,6 +31,7 @@ dependencies = [
     "litellm>=1.81.0",
     "dnspython>=2.4.0",
     "resend>=2.0.0",
+    "google-analytics-data>=0.18.0",
     "framework",
     "stripe>=14.3.0",
     "arxiv>=2.1.0",

tools/src/aden_tools/credentials/__init__.py

@@ -41,6 +41,7 @@
 - github.py: GitHub API credentials
 - hubspot.py: HubSpot CRM credentials
 - slack.py: Slack workspace credentials
+- google_analytics.py: Google Analytics credentials
 - google_maps.py: Google Maps Platform credentials
 - calcom.py: Cal.com scheduling API credentials
 
@@ -63,6 +64,7 @@
 from .email import EMAIL_CREDENTIALS
 from .gcp_vision import GCP_VISION_CREDENTIALS
 from .github import GITHUB_CREDENTIALS
+from .google_analytics import GOOGLE_ANALYTICS_CREDENTIALS
 from .google_calendar import GOOGLE_CALENDAR_CREDENTIALS
 from .google_docs import GOOGLE_DOCS_CREDENTIALS
 from .google_maps import GOOGLE_MAPS_CREDENTIALS
@@ -100,6 +102,7 @@
     **APOLLO_CREDENTIALS,
     **DISCORD_CREDENTIALS,
     **GITHUB_CREDENTIALS,
+    **GOOGLE_ANALYTICS_CREDENTIALS,
     **GOOGLE_DOCS_CREDENTIALS,
     **GOOGLE_MAPS_CREDENTIALS,
     **HUBSPOT_CREDENTIALS,
@@ -145,6 +148,7 @@
     "EMAIL_CREDENTIALS",
     "GCP_VISION_CREDENTIALS",
     "GITHUB_CREDENTIALS",
+    "GOOGLE_ANALYTICS_CREDENTIALS",
     "GOOGLE_DOCS_CREDENTIALS",
     "GOOGLE_MAPS_CREDENTIALS",
     "HUBSPOT_CREDENTIALS",

tools/src/aden_tools/credentials/bigquery.py

@@ -9,6 +9,7 @@
 BIGQUERY_CREDENTIALS = {
     "bigquery": CredentialSpec(
         env_var="GOOGLE_APPLICATION_CREDENTIALS",
+        credential_group="google_cloud",
         tools=["run_bigquery_query", "describe_dataset"],
         required=False,  # Falls back to ADC if not set
         startup_required=False,

tools/src/aden_tools/credentials/google_analytics.py

@@ -0,0 +1,41 @@
+"""
+Google Analytics credentials.
+
+Contains credentials for Google Analytics 4 Data API integration.
+"""
+
+from .base import CredentialSpec
+
+GOOGLE_ANALYTICS_CREDENTIALS = {
+    "google_analytics": CredentialSpec(
+        env_var="GOOGLE_APPLICATION_CREDENTIALS",
+        credential_group="google_cloud",
+        tools=[
+            "ga_run_report",
+            "ga_get_realtime",
+            "ga_get_top_pages",
+            "ga_get_traffic_sources",
+        ],
+        required=True,
+        startup_required=False,
+        help_url="https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart-client-libraries",
+        description="Path to Google Cloud service account JSON key with Analytics read access",
+        # Auth method support
+        aden_supported=False,
+        direct_api_key_supported=True,
+        api_key_instructions="""To set up Google Analytics credentials:
+1. Go to Google Cloud Console > IAM & Admin > Service Accounts
+2. Create a service account (e.g., "hive-analytics-reader")
+3. Download the JSON key file
+4. In Google Analytics, go to Admin > Property > Property Access Management
+5. Add the service account email with "Viewer" role
+6. Set the env var to the path of the JSON key file:
+   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json""",
+        # Health check - GA4 Data API doesn't have a simple health endpoint
+        health_check_endpoint="",
+        health_check_method="GET",
+        # Credential store mapping
+        credential_id="google_analytics",
+        credential_key="service_account_key_path",
+    ),
+}

tools/src/aden_tools/tools/__init__.py

@@ -54,6 +54,7 @@
 from .file_system_toolkits.write_to_file import register_tools as register_write_to_file
 from .github_tool import register_tools as register_github
 from .gmail_tool import register_tools as register_gmail
+from .google_analytics_tool import register_tools as register_google_analytics
 from .google_docs_tool import register_tools as register_google_docs
 from .google_maps_tool import register_tools as register_google_maps
 from .http_headers_scanner import register_tools as register_http_headers_scanner
@@ -126,6 +127,7 @@ def register_all_tools(
     register_slack(mcp, credentials=credentials)
     register_telegram(mcp, credentials=credentials)
     register_vision(mcp, credentials=credentials)
+    register_google_analytics(mcp, credentials=credentials)
     register_google_docs(mcp, credentials=credentials)
     register_google_maps(mcp, credentials=credentials)
     register_account_info(mcp, credentials=credentials)

tools/src/aden_tools/tools/google_analytics_tool/README.md

@@ -0,0 +1,124 @@
+# Google Analytics Tool
+
+Query GA4 website traffic and marketing performance data via the Data API v1.
+
+## Description
+
+Provides read-only access to Google Analytics 4 (GA4) properties. Use these tools to pull website traffic data, monitor real-time activity, and analyze marketing performance.
+
+Supports:
+- **Custom reports** with any combination of GA4 dimensions and metrics
+- **Real-time data** for current website activity
+- **Convenience wrappers** for common queries (top pages, traffic sources)
+
+## Tools
+
+### `ga_run_report`
+
+Run a custom GA4 report with flexible dimensions, metrics, and date ranges.
+
+| Argument | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `property_id` | str | Yes | - | GA4 property ID (e.g., `"properties/123456"`) |
+| `metrics` | list[str] | Yes | - | Metrics to retrieve (e.g., `["sessions", "totalUsers"]`) |
+| `dimensions` | list[str] | No | `None` | Dimensions to group by (e.g., `["pagePath", "sessionSource"]`) |
+| `start_date` | str | No | `"28daysAgo"` | Start date (e.g., `"2024-01-01"` or `"7daysAgo"`) |
+| `end_date` | str | No | `"today"` | End date |
+| `limit` | int | No | `100` | Max rows to return (1-10000) |
+
+### `ga_get_realtime`
+
+Get real-time analytics data (active users, current pages).
+
+| Argument | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `property_id` | str | Yes | - | GA4 property ID |
+| `metrics` | list[str] | No | `["activeUsers"]` | Metrics to retrieve |
+
+### `ga_get_top_pages`
+
+Get top pages by views and engagement (convenience wrapper).
+
+| Argument | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `property_id` | str | Yes | - | GA4 property ID |
+| `start_date` | str | No | `"28daysAgo"` | Start date |
+| `end_date` | str | No | `"today"` | End date |
+| `limit` | int | No | `10` | Max pages to return (1-10000) |
+
+Returns: `pagePath`, `pageTitle`, `screenPageViews`, `averageSessionDuration`, `bounceRate`
+
+### `ga_get_traffic_sources`
+
+Get traffic breakdown by source/medium (convenience wrapper).
+
+| Argument | Type | Required | Default | Description |
+|----------|------|----------|---------|-------------|
+| `property_id` | str | Yes | - | GA4 property ID |
+| `start_date` | str | No | `"28daysAgo"` | Start date |
+| `end_date` | str | No | `"today"` | End date |
+| `limit` | int | No | `10` | Max sources to return (1-10000) |
+
+Returns: `sessionSource`, `sessionMedium`, `sessions`, `totalUsers`, `conversions`
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GOOGLE_APPLICATION_CREDENTIALS` | Yes | Path to Google Cloud service account JSON key file |
+
+## Setup
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/) > IAM & Admin > Service Accounts
+2. Create a service account (e.g., "hive-analytics-reader")
+3. Download the JSON key file
+4. Enable the **Google Analytics Data API** in your Google Cloud project
+5. In Google Analytics, go to Admin > Property > Property Access Management
+6. Add the service account email with **Viewer** role
+7. Set the environment variable:
+   ```bash
+   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
+   ```
+
+## Common GA4 Metrics
+
+`sessions`, `totalUsers`, `newUsers`, `screenPageViews`, `conversions`, `bounceRate`, `averageSessionDuration`, `engagedSessions`
+
+## Common GA4 Dimensions
+
+`pagePath`, `pageTitle`, `sessionSource`, `sessionMedium`, `country`, `deviceCategory`, `date`
+
+## Example Usage
+
+```python
+# Custom report: sessions by page over the last 7 days
+result = ga_run_report(
+    property_id="properties/123456",
+    metrics=["sessions", "screenPageViews"],
+    dimensions=["pagePath"],
+    start_date="7daysAgo",
+)
+
+# Real-time active users
+result = ga_get_realtime(property_id="properties/123456")
+
+# Top 10 pages this month
+result = ga_get_top_pages(
+    property_id="properties/123456",
+    start_date="2024-01-01",
+    end_date="2024-01-31",
+)
+
+# Traffic sources breakdown
+result = ga_get_traffic_sources(property_id="properties/123456")
+```
+
+## Error Handling
+
+Returns error dicts for common issues:
+- `Google Analytics credentials not configured` - No credentials set
+- `property_id must start with 'properties/'` - Invalid property ID format
+- `metrics list must not be empty` - No metrics provided
+- `limit must be between 1 and 10000` - Limit out of bounds
+- `Failed to initialize Google Analytics client` - Bad credentials file
+- `Google Analytics API error: ...` - API-level errors (permissions, quota, etc.)

tools/src/aden_tools/tools/google_analytics_tool/__init__.py

@@ -0,0 +1,5 @@
+"""Google Analytics Tool - Query GA4 website traffic and marketing data."""
+
+from .google_analytics_tool import register_tools
+
+__all__ = ["register_tools"]