From 40bda49c1c8b0198288235c966a207f45b560fc1 Mon Sep 17 00:00:00 2001 From: marcusquinn <6428977+marcusquinn@users.noreply.github.com> Date: Wed, 14 Jan 2026 19:53:49 +0000 Subject: [PATCH 1/2] feat(mcp): add Google Analytics MCP integration - Add google-analytics.md subagent in services/analytics/ - Add analytics-mcp config to mcp-servers-config.json.txt (disabled by default) - Update seo.md, marketing.md, sales.md to reference google-analytics subagent - Update AGENTS.md subagent folders table with services/analytics/ The MCP is disabled globally and enabled per-agent via tools: analytics_mcp_*: true when the google-analytics subagent is loaded by seo, marketing, or sales agents. --- .agent/AGENTS.md | 2 + .agent/marketing.md | 11 + .agent/sales.md | 14 +- .agent/seo.md | 13 +- .agent/services/analytics/google-analytics.md | 418 ++++++++++++++++++ configs/mcp-servers-config.json.txt | 9 + 6 files changed, 463 insertions(+), 4 deletions(-) create mode 100644 .agent/services/analytics/google-analytics.md diff --git a/.agent/AGENTS.md b/.agent/AGENTS.md index 00c137624..571c0fe9d 100644 --- a/.agent/AGENTS.md +++ b/.agent/AGENTS.md @@ -398,6 +398,7 @@ Subagents provide specialized capabilities. Read them when tasks require domain | `services/email/` | Email services - transactional email, deliverability | ses | | `services/communications/` | Communications platform - SMS, voice, WhatsApp, verify, recordings | twilio, telfon | | `services/crm/` | CRM integration - contact management, email marketing, automation | fluentcrm | +| `services/analytics/` | Website analytics - GA4 reporting, traffic analysis, real-time data, e-commerce tracking | google-analytics | | `services/accounting/` | Accounting integration - invoicing, expenses, financial reports | quickfile | | `workflows/` | Development processes - branching, releases, PR reviews, quality gates | git-workflow, plans, release, version-bump, pr, review-issue-pr, preflight, postflight, ralph-loop, session-review | | `templates/` | Document templates - PRDs, task lists, planning documents | prd-template, tasks-template, plans-template, todo-template | @@ -479,6 +480,7 @@ For AI-assisted setup guidance, see `aidevops/setup.md`. | WordPress work | `tools/wordpress/wp-dev.md`, `tools/wordpress/mainwp.md` | | SEO analysis | `seo/dataforseo.md`, `seo/google-search-console.md` | | Sitemap submission | `seo/gsc-sitemaps.md` | +| Website analytics | `services/analytics/google-analytics.md` (GA4 reports, traffic, conversions) | | CRM/email marketing | `services/crm/fluentcrm.md` | | MCP development | `tools/build-mcp/build-mcp.md`, `tools/build-mcp/server-patterns.md` | | Agent design | `tools/build-agent/build-agent.md`, `tools/build-agent/agent-review.md` | diff --git a/.agent/marketing.md b/.agent/marketing.md index 8d629ec8e..ae7e545de 100644 --- a/.agent/marketing.md +++ b/.agent/marketing.md @@ -24,6 +24,7 @@ subagents: - bird # Analytics - google-search-console + - google-analytics # Built-in - general - explore @@ -44,6 +45,7 @@ subagents: - `seo.md` - Search optimization - `sales.md` - Sales alignment and lead handoff - `services/crm/fluentcrm.md` - CRM operations (detailed) +- `services/analytics/google-analytics.md` - GA4 reporting and traffic analysis **FluentCRM MCP Tools**: @@ -57,6 +59,14 @@ subagents: | **Smart Links** | `fluentcrm_create_smart_link`, `fluentcrm_generate_smart_link_shortcode` | | **Reports** | `fluentcrm_dashboard_stats` | +**Google Analytics MCP Tools** (when `google-analytics` subagent loaded): + +| Category | Key Tools | +|----------|-----------| +| **Account Info** | `get_account_summaries`, `get_property_details` | +| **Reports** | `run_report`, `get_custom_dimensions_and_metrics` | +| **Real-time** | `run_realtime_report` | + **Typical Tasks**: - Email campaign creation and management @@ -64,6 +74,7 @@ subagents: - Audience segmentation - Lead nurturing sequences - Campaign performance analysis +- Website traffic and conversion analytics (GA4) diff --git a/.agent/sales.md b/.agent/sales.md index 1649fd4fd..a0dc2f645 100644 --- a/.agent/sales.md +++ b/.agent/sales.md @@ -20,6 +20,8 @@ subagents: # Research - outscraper - crawl4ai + # Analytics + - google-analytics # Built-in - general - explore @@ -39,7 +41,8 @@ subagents: - `marketing.md` - Lead generation and campaigns - `content.md` - Sales collateral and proposals - `services/accounting/quickfile.md` - Invoicing and payments -- `.agent/services/crm/fluentcrm.md` - CRM operations (detailed) +- `services/crm/fluentcrm.md` - CRM operations (detailed) +- `services/analytics/google-analytics.md` - GA4 e-commerce and conversion tracking **FluentCRM MCP Tools**: @@ -55,6 +58,14 @@ subagents: | **Smart Links** | `fluentcrm_list_smart_links`, `fluentcrm_create_smart_link`, `fluentcrm_generate_smart_link_shortcode`, `fluentcrm_validate_smart_link_data` | | **Reports** | `fluentcrm_dashboard_stats`, `fluentcrm_custom_fields` | +**Google Analytics MCP Tools** (when `google-analytics` subagent loaded): + +| Category | Key Tools | +|----------|-----------| +| **Account Info** | `get_account_summaries`, `get_property_details` | +| **Reports** | `run_report`, `get_custom_dimensions_and_metrics` | +| **Real-time** | `run_realtime_report` | + **Typical Tasks**: - Lead capture and qualification @@ -62,6 +73,7 @@ subagents: - Contact segmentation - Sales automation setup - Quote and proposal generation +- E-commerce and conversion analytics (GA4) diff --git a/.agent/seo.md b/.agent/seo.md index c0353fcc1..0cd087188 100644 --- a/.agent/seo.md +++ b/.agent/seo.md @@ -12,6 +12,7 @@ subagents: - eeat-score - domain-research - pagespeed + - google-analytics - general - explore --- @@ -23,11 +24,11 @@ subagents: ## Quick Reference - **Purpose**: SEO optimization and analysis -- **Tools**: Google Search Console, Ahrefs, DataForSEO, Serper, PageSpeed Insights, Context7 -- **MCP**: GSC, DataForSEO, Serper, Context7 for comprehensive SEO data and library docs +- **Tools**: Google Search Console, Ahrefs, DataForSEO, Serper, PageSpeed Insights, Google Analytics, Context7 +- **MCP**: GSC, DataForSEO, Serper, Google Analytics, Context7 for comprehensive SEO data and library docs - **Commands**: `/keyword-research`, `/autocomplete-research`, `/keyword-research-extended` -**Subagents** (`seo/`): +**Subagents** (`seo/` and `services/analytics/`): | Subagent | Purpose | |----------|---------| @@ -38,6 +39,7 @@ subagents: | `serper.md` | Google Search API (web, images, news, places) | | `site-crawler.md` | SEO site auditing (Screaming Frog-like capabilities) | | `eeat-score.md` | E-E-A-T content quality scoring and analysis | +| `google-analytics.md` | GA4 reporting, traffic analysis, and user behavior (see `services/analytics/`) | **Key Operations**: - Keyword research with weakness detection (`/keyword-research-extended`) @@ -83,6 +85,11 @@ dataforseo.backlinks [domain] # Serper via MCP serper.google_search [query] serper.google_search_news [query] + +# Google Analytics via MCP (when google-analytics subagent loaded) +get_account_summaries +run_report [property_id] [dimensions] [metrics] [date_range] +run_realtime_report [property_id] [dimensions] [metrics] ``` **Testing**: Use OpenCode CLI to test SEO commands without restarting TUI: diff --git a/.agent/services/analytics/google-analytics.md b/.agent/services/analytics/google-analytics.md new file mode 100644 index 000000000..ffed556c3 --- /dev/null +++ b/.agent/services/analytics/google-analytics.md @@ -0,0 +1,418 @@ +--- +description: Google Analytics MCP - GA4 reporting, account management, and real-time analytics +mode: subagent +tools: + read: true + write: false + edit: false + bash: true + glob: true + grep: true + webfetch: true + analytics_mcp_*: true +--- + +# Google Analytics MCP Integration + + + +## Quick Reference + +- **Type**: Google Analytics 4 (GA4) API integration +- **MCP Server**: `analytics-mcp` (official Google package via pipx) +- **Auth**: Google Cloud Application Default Credentials (ADC) +- **APIs**: Google Analytics Admin API, Google Analytics Data API +- **Capabilities**: Account summaries, property details, reports, real-time data, custom dimensions/metrics + +**Environment Variables**: + +```bash +export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json" +export GOOGLE_PROJECT_ID="your-gcp-project-id" +``` + +**MCP Tools Available**: + +| Category | Tools | +|----------|-------| +| **Account Info** | `get_account_summaries`, `get_property_details`, `list_google_ads_links` | +| **Reports** | `run_report`, `get_custom_dimensions_and_metrics` | +| **Real-time** | `run_realtime_report` | + + + +Google Analytics MCP provides AI-assisted access to Google Analytics 4 data for website analytics, user behavior analysis, and marketing performance tracking. + +## Installation + +### Prerequisites + +1. **Python with pipx**: Install pipx for isolated Python package management +2. **Google Cloud Project**: With Analytics APIs enabled +3. **Google Analytics Access**: User credentials with GA4 property access + +### Enable Google Cloud APIs + +Enable these APIs in your Google Cloud project: + +- [Google Analytics Admin API](https://console.cloud.google.com/apis/library/analyticsadmin.googleapis.com) +- [Google Analytics Data API](https://console.cloud.google.com/apis/library/analyticsdata.googleapis.com) + +### Configure Credentials + +Set up Application Default Credentials (ADC) with the analytics readonly scope: + +```bash +# Using OAuth desktop/web client +gcloud auth application-default login \ + --scopes https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform \ + --client-id-file=YOUR_CLIENT_JSON_FILE + +# Or using service account impersonation +gcloud auth application-default login \ + --impersonate-service-account=SERVICE_ACCOUNT_EMAIL \ + --scopes=https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform +``` + +After authentication, note the credentials file path printed: +```text +Credentials saved to file: [PATH_TO_CREDENTIALS_JSON] +``` + +### OpenCode Configuration + +Add to `~/.config/opencode/opencode.json` (disabled globally for token efficiency): + +```json +{ + "mcp": { + "analytics-mcp": { + "type": "local", + "command": ["pipx", "run", "analytics-mcp"], + "env": { + "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json", + "GOOGLE_PROJECT_ID": "your-project-id" + }, + "enabled": false + } + } +} +``` + +**Per-Agent Enablement**: Google Analytics tools are enabled via `analytics_mcp_*: true` in this subagent's `tools:` section. Main agents (`seo.md`, `marketing.md`, `sales.md`) reference this subagent for analytics operations, ensuring the MCP is only loaded when needed. + +### Claude Desktop Configuration + +Add to Claude Desktop MCP settings (`~/.gemini/settings.json` for Gemini): + +```json +{ + "mcpServers": { + "analytics-mcp": { + "command": "pipx", + "args": ["run", "analytics-mcp"], + "env": { + "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/credentials.json", + "GOOGLE_PROJECT_ID": "your-project-id" + } + } + } +} +``` + +## Account & Property Management + +### Get Account Summaries + +Retrieve information about accessible Google Analytics accounts and properties: + +```text +Use get_account_summaries to list all GA4 accounts and properties +the authenticated user has access to. + +Returns: +- Account names and IDs +- Property names and IDs +- Property types (GA4, Universal Analytics) +``` + +### Get Property Details + +Get detailed information about a specific GA4 property: + +```text +Use get_property_details with property ID to get: +- Property display name +- Time zone +- Currency +- Industry category +- Service level +- Create/update timestamps +``` + +### List Google Ads Links + +View Google Ads account connections for a property: + +```text +Use list_google_ads_links with property ID to see: +- Linked Google Ads accounts +- Link status +- Ads personalization settings +``` + +## Running Reports + +### Standard Reports + +Run GA4 reports using the Data API: + +```text +Use run_report with: +- property_id: GA4 property ID (e.g., "properties/123456789") +- date_range: Start and end dates +- dimensions: Dimensions to include (e.g., "country", "deviceCategory") +- metrics: Metrics to include (e.g., "activeUsers", "sessions") +- dimension_filter: Optional filters +- metric_filter: Optional metric filters +- order_bys: Sort order +- limit: Row limit +``` + +### Common Report Examples + +**Traffic Overview**: +```text +run_report with: +- dimensions: ["date"] +- metrics: ["activeUsers", "sessions", "screenPageViews"] +- date_range: last 30 days +``` + +**Top Pages**: +```text +run_report with: +- dimensions: ["pagePath", "pageTitle"] +- metrics: ["screenPageViews", "averageSessionDuration"] +- order_by: screenPageViews descending +- limit: 20 +``` + +**Traffic Sources**: +```text +run_report with: +- dimensions: ["sessionSource", "sessionMedium"] +- metrics: ["sessions", "activeUsers", "conversions"] +``` + +**Geographic Distribution**: +```text +run_report with: +- dimensions: ["country", "city"] +- metrics: ["activeUsers", "sessions"] +``` + +**Device Breakdown**: +```text +run_report with: +- dimensions: ["deviceCategory", "operatingSystem"] +- metrics: ["activeUsers", "sessions"] +``` + +### Custom Dimensions & Metrics + +Retrieve custom dimension and metric definitions: + +```text +Use get_custom_dimensions_and_metrics with property ID to get: +- Custom dimension names and scopes +- Custom metric names and types +- Parameter names for implementation +``` + +## Real-time Analytics + +### Real-time Reports + +Get live data about current website activity: + +```text +Use run_realtime_report with: +- property_id: GA4 property ID +- dimensions: Real-time dimensions (e.g., "country", "deviceCategory") +- metrics: Real-time metrics (e.g., "activeUsers") +``` + +### Real-time Use Cases + +**Current Active Users**: +```text +run_realtime_report with: +- metrics: ["activeUsers"] +``` + +**Active Users by Page**: +```text +run_realtime_report with: +- dimensions: ["unifiedScreenName"] +- metrics: ["activeUsers"] +``` + +**Active Users by Source**: +```text +run_realtime_report with: +- dimensions: ["sessionSource"] +- metrics: ["activeUsers"] +``` + +## SEO Integration + +### Search Performance Correlation + +Combine GA4 data with Google Search Console for comprehensive SEO analysis: + +1. **Traffic Analysis**: Use GA4 for on-site behavior metrics +2. **Search Performance**: Use GSC for search impressions and clicks +3. **Correlation**: Match landing pages between both data sources + +### Content Performance + +Analyze content effectiveness for SEO: + +```text +run_report with: +- dimensions: ["landingPage", "sessionSource"] +- metrics: ["sessions", "bounceRate", "averageSessionDuration", "conversions"] +- dimension_filter: sessionSource = "google" +``` + +## Marketing Integration + +### Campaign Performance + +Track marketing campaign effectiveness: + +```text +run_report with: +- dimensions: ["sessionCampaignName", "sessionSource", "sessionMedium"] +- metrics: ["sessions", "activeUsers", "conversions", "totalRevenue"] +``` + +### Conversion Analysis + +Analyze conversion funnels and goals: + +```text +run_report with: +- dimensions: ["eventName"] +- metrics: ["eventCount", "conversions"] +- dimension_filter: eventName matches conversion events +``` + +### Audience Insights + +Understand audience demographics and behavior: + +```text +run_report with: +- dimensions: ["userAgeBracket", "userGender"] +- metrics: ["activeUsers", "sessions", "conversions"] +``` + +## Sales Integration + +### E-commerce Analytics + +Track sales and revenue metrics: + +```text +run_report with: +- dimensions: ["itemName", "itemCategory"] +- metrics: ["itemRevenue", "itemsPurchased", "itemsViewed"] +``` + +### Lead Generation + +Track lead generation performance: + +```text +run_report with: +- dimensions: ["sessionSource", "sessionMedium", "landingPage"] +- metrics: ["conversions"] +- dimension_filter: eventName = "generate_lead" +``` + +## Best Practices + +### API Usage + +- Use date ranges appropriate to your analysis needs +- Limit dimensions to avoid sparse data +- Use filters to focus on relevant data +- Cache results for repeated queries + +### Data Quality + +- Verify property ID before running reports +- Check for data sampling in large datasets +- Consider data freshness (real-time vs. processed) +- Validate custom dimension/metric implementations + +### Performance + +- Use pagination for large result sets +- Batch related queries when possible +- Consider quotas and rate limits +- Use real-time API sparingly (higher cost) + +## Troubleshooting + +### Authentication Errors + +```bash +# Verify credentials are valid +gcloud auth application-default print-access-token + +# Re-authenticate if needed +gcloud auth application-default login \ + --scopes https://www.googleapis.com/auth/analytics.readonly +``` + +### API Not Enabled + +If you receive "API not enabled" errors: + +1. Go to Google Cloud Console +2. Navigate to APIs & Services > Library +3. Enable "Google Analytics Admin API" +4. Enable "Google Analytics Data API" + +### No Data Returned + +- Verify property ID format: `properties/123456789` +- Check date range has data +- Verify dimensions/metrics are valid for GA4 +- Ensure user has access to the property + +### Rate Limiting + +Google Analytics API has quotas: + +- Requests per day per project +- Requests per minute per user +- Tokens per day per project + +For high-volume usage, implement: +- Request batching +- Response caching +- Exponential backoff + +## Related Documentation + +- `seo.md` - SEO workflows with Google Analytics +- `marketing.md` - Marketing analytics with GA4 +- `sales.md` - Sales analytics and e-commerce tracking +- `seo/google-search-console.md` - GSC integration for search data +- Google Analytics MCP: https://github.com/googleanalytics/google-analytics-mcp +- GA4 Data API: https://developers.google.com/analytics/devguides/reporting/data/v1 +- GA4 Admin API: https://developers.google.com/analytics/devguides/config/admin/v1 diff --git a/configs/mcp-servers-config.json.txt b/configs/mcp-servers-config.json.txt index 1c7cb46a1..64d38c53d 100644 --- a/configs/mcp-servers-config.json.txt +++ b/configs/mcp-servers-config.json.txt @@ -65,6 +65,15 @@ "PEEKABOO_AI_PROVIDERS": "openai/gpt-4o" }, "description": "Peekaboo MCP server for macOS screen capture, AI vision analysis, and GUI automation" + }, + "analytics-mcp": { + "command": "pipx", + "args": ["run", "analytics-mcp"], + "env": { + "GOOGLE_APPLICATION_CREDENTIALS": "YOUR_CREDENTIALS_JSON_PATH_HERE", + "GOOGLE_PROJECT_ID": "YOUR_GCP_PROJECT_ID_HERE" + }, + "description": "Google Analytics MCP server for GA4 reporting, account management, and real-time analytics. Requires pipx and Google Cloud ADC setup." } } } From 38c65cd3ec2673850439b268687e7d8eafe686f1 Mon Sep 17 00:00:00 2001 From: marcusquinn <6428977+marcusquinn@users.noreply.github.com> Date: Wed, 14 Jan 2026 19:59:46 +0000 Subject: [PATCH 2/2] fix: address CodeRabbit review feedback - Add blank line before code block in google-analytics.md (markdown lint) - Fix heading: 'Claude Desktop' -> 'Gemini CLI' for ~/.gemini/settings.json - Add missing list_google_ads_links tool to marketing.md and sales.md --- .agent/marketing.md | 2 +- .agent/sales.md | 2 +- .agent/services/analytics/google-analytics.md | 5 +++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.agent/marketing.md b/.agent/marketing.md index ae7e545de..17b8a7e57 100644 --- a/.agent/marketing.md +++ b/.agent/marketing.md @@ -63,7 +63,7 @@ subagents: | Category | Key Tools | |----------|-----------| -| **Account Info** | `get_account_summaries`, `get_property_details` | +| **Account Info** | `get_account_summaries`, `get_property_details`, `list_google_ads_links` | | **Reports** | `run_report`, `get_custom_dimensions_and_metrics` | | **Real-time** | `run_realtime_report` | diff --git a/.agent/sales.md b/.agent/sales.md index a0dc2f645..04f6b72d0 100644 --- a/.agent/sales.md +++ b/.agent/sales.md @@ -62,7 +62,7 @@ subagents: | Category | Key Tools | |----------|-----------| -| **Account Info** | `get_account_summaries`, `get_property_details` | +| **Account Info** | `get_account_summaries`, `get_property_details`, `list_google_ads_links` | | **Reports** | `run_report`, `get_custom_dimensions_and_metrics` | | **Real-time** | `run_realtime_report` | diff --git a/.agent/services/analytics/google-analytics.md b/.agent/services/analytics/google-analytics.md index ffed556c3..a066bdead 100644 --- a/.agent/services/analytics/google-analytics.md +++ b/.agent/services/analytics/google-analytics.md @@ -75,6 +75,7 @@ gcloud auth application-default login \ ``` After authentication, note the credentials file path printed: + ```text Credentials saved to file: [PATH_TO_CREDENTIALS_JSON] ``` @@ -101,9 +102,9 @@ Add to `~/.config/opencode/opencode.json` (disabled globally for token efficienc **Per-Agent Enablement**: Google Analytics tools are enabled via `analytics_mcp_*: true` in this subagent's `tools:` section. Main agents (`seo.md`, `marketing.md`, `sales.md`) reference this subagent for analytics operations, ensuring the MCP is only loaded when needed. -### Claude Desktop Configuration +### Gemini CLI Configuration -Add to Claude Desktop MCP settings (`~/.gemini/settings.json` for Gemini): +Add to Gemini CLI settings (`~/.gemini/settings.json`): ```json {