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

tools/pyproject.toml

@@ -30,6 +30,7 @@ dependencies = [
     "playwright-stealth>=1.0.5",
     "litellm>=1.81.0",
     "resend>=2.0.0",
+    "google-analytics-data>=0.18.0",
     "framework",
 ]
 

tools/src/aden_tools/credentials/__init__.py

@@ -55,6 +55,7 @@
 from .browser import get_aden_auth_url, get_aden_setup_url, open_browser
 from .email import EMAIL_CREDENTIALS
 from .github import GITHUB_CREDENTIALS
+from .google_analytics import GOOGLE_ANALYTICS_CREDENTIALS
 from .health_check import HealthCheckResult, check_credential_health
 from .hubspot import HUBSPOT_CREDENTIALS
 from .llm import LLM_CREDENTIALS
@@ -77,6 +78,7 @@
     **GITHUB_CREDENTIALS,
     **HUBSPOT_CREDENTIALS,
     **SLACK_CREDENTIALS,
+    **GOOGLE_ANALYTICS_CREDENTIALS,
 }
 
 __all__ = [
@@ -108,4 +110,5 @@
     "HUBSPOT_CREDENTIALS",
     "SLACK_CREDENTIALS",
     "APOLLO_CREDENTIALS",
+    "GOOGLE_ANALYTICS_CREDENTIALS",
 ]

tools/src/aden_tools/credentials/google_analytics.py

@@ -0,0 +1,40 @@
+"""
+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",
+        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

@@ -41,6 +41,7 @@
 from .file_system_toolkits.view_file import register_tools as register_view_file
 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 .google_analytics_tool import register_tools as register_google_analytics
 from .hubspot_tool import register_tools as register_hubspot
 from .pdf_read_tool import register_tools as register_pdf_read
 from .runtime_logs_tool import register_tools as register_runtime_logs
@@ -79,6 +80,7 @@ def register_all_tools(
     register_hubspot(mcp, credentials=credentials)
     register_apollo(mcp, credentials=credentials)
     register_slack(mcp, credentials=credentials)
+    register_google_analytics(mcp, credentials=credentials)
 
     # Register file system toolkits
     register_view_file(mcp)
@@ -209,6 +211,10 @@ def register_all_tools(
         "slack_kick_user_from_channel",
         "slack_delete_file",
         "slack_get_team_stats",
+        "ga_run_report",
+        "ga_get_realtime",
+        "ga_get_top_pages",
+        "ga_get_traffic_sources",
     ]
 
 

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"]