Query your GA4 property from any MCP-compatible client — traffic reports, top pages, active users, events, user behavior, organic landing pages, ecommerce revenue, and SEO growth monitoring. Works with Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Hermes, Open Claw Agent, Codex-style coding agents, and any tool supporting the Model Context Protocol.
This repository is evolving from a generic GA4 reporting helper into a GA4 growth intelligence skill: setup → readiness validation → organic/channel diagnostics → landing page + conversion analysis → ecommerce/revenue analysis → GSC join → recurring cron monitoring → experiment follow-up.
- audit Organic Search landing pages
- find pages with traffic but no conversions
- detect organic page decay vs previous period
- measure content clusters, not just isolated URLs
- connect SEO traffic to conversions/revenue
- analyze ecommerce product/collection organic value
- compare channel mix: Organic, Paid, Direct, Referral, Email
- split organic performance by country and device
- join GSC query/page data with GA4 landing-page behavior
- run daily/weekly monitoring prompts or cron jobs
- follow up SEO experiments after 7/14/28/60/90 days
This project packages the mcp-server-google-analytics MCP server with ready-to-use configuration and an optional Claude Code skill file for guided workflows.
The MCP server connects to the GA4 Data API using a Google service account and exposes 5 tools that any MCP client can call.
- Node.js 20+
- A Google Cloud project with the Analytics Data API enabled
- A service account with Viewer access to your GA4 property
- Go to Google Cloud Console and create a project (or use an existing one)
- Enable the Google Analytics Data API (APIs & Services > Library > search "Analytics Data API")
- Create a service account (IAM & Admin > Service Accounts > Create)
- Create and download a JSON key for the service account
- In Google Analytics > Admin > Property Access Management, add the service account email as a Viewer
Create or edit your MCP configuration file:
Claude Desktop — claude_desktop_config.json
{
"mcpServers": {
"google-analytics": {
"command": "npx",
"args": ["-y", "mcp-server-google-analytics"],
"env": {
"GOOGLE_CLIENT_EMAIL": "your-service-account@project.iam.gserviceaccount.com",
"GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
"GA_PROPERTY_ID": "123456789"
}
}
}
}Config location: %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
Claude Code — .mcp.json (project root)
{
"mcpServers": {
"google-analytics": {
"command": "npx",
"args": ["-y", "mcp-server-google-analytics"],
"env": {
"GOOGLE_CLIENT_EMAIL": "your-service-account@project.iam.gserviceaccount.com",
"GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----",
"GA_PROPERTY_ID": "123456789"
}
}
}
}Cursor / Windsurf / Cline
Use the same JSON structure above in your editor's MCP configuration. Check your editor's docs for the config file location:
- Cursor:
.cursor/mcp.json - Windsurf:
~/.codeium/windsurf/mcp_config.json - Cline: VS Code settings > Cline MCP Servers
Tip: Your
GA_PROPERTY_IDis the numeric ID from GA4 Admin > Property Settings (e.g.123456789). Do not include theproperties/prefix.
Restart your MCP client and ask: "Show me my active users for the last 7 days"
MCP is excellent for local/manual agent workflows. For production client agents and recurring pipelines, direct GA4 Data API scripts are often better because they provide typed outputs, retries, quota handling, property/account selection, and easier credential isolation.
Recommended split:
MCP = local/manual assistant access
Direct GA4 Data API = durable scheduled pipeline
BigQuery export = deep journey/cohort analysis
See references/mcp-vs-direct-api.md.
Do not treat GA4 access as simply “configured / not configured”. Track readiness states:
missing_credentials → credentials_present → service_account_valid → property_access_missing/property_id_invalid → first_query_passed → production_ready
Never commit real .mcp.json, service-account JSON keys, private keys, .env, or client secrets. Use [REDACTED] in examples.
See references/readiness-and-secret-safety.md and templates/ga4-readiness-checklist.md.
| Tool | Description | Key Parameters |
|---|---|---|
runReport |
Flexible custom reports with any dimensions/metrics | startDate, endDate, dimensions, metrics, dimensionFilter |
getPageViews |
Page view metrics by dimension | startDate, endDate, dimensions |
getActiveUsers |
Active users over time | startDate, endDate |
getEvents |
Event analysis | startDate, endDate, eventName |
getUserBehavior |
Session duration, bounce rate, engagement | startDate, endDate |
Ask your AI assistant in natural language:
- "Show me my top 10 pages by views this month"
- "How many active users did I have last week vs the week before?"
- "What events are firing most on my site?"
- "Break down my traffic by country for the last 30 days"
- "What's my bounce rate trend over the past 3 months?"
- "Compare desktop vs mobile sessions this quarter"
- "Which traffic sources are driving the most conversions?"
| Dimension | Description |
|---|---|
date |
Date in YYYYMMDD format |
city |
User's city |
country |
User's country |
deviceCategory |
desktop, mobile, or tablet |
sessionSource |
Traffic source (google, direct, etc.) |
sessionMedium |
Traffic medium (organic, cpc, referral, etc.) |
pagePath |
URL path of the page |
pageTitle |
Title of the page |
eventName |
Name of the event |
browser |
User's browser |
operatingSystem |
User's OS |
| Metric | Description |
|---|---|
activeUsers |
Users who had an engaged session |
newUsers |
First-time users |
sessions |
Total sessions |
screenPageViews |
Total page views |
eventCount |
Total events fired |
conversions |
Conversion events |
totalRevenue |
Total revenue (if ecommerce is set up) |
bounceRate |
Percentage of non-engaged sessions |
averageSessionDuration |
Average session length in seconds |
engagedSessions |
Sessions with engagement |
This repo includes reusable workflows and report templates for analytics-driven SEO growth:
| Area | File |
|---|---|
| Organic landing pages, page decay, clusters, channel mix | references/seo-growth-ga4-workflows.md |
| Ecommerce/revenue analytics | references/ecommerce-revenue-workflows.md |
| GSC + GA4 joined opportunities | references/gsc-ga4-join-workflow.md |
| Daily/weekly monitoring and experiment follow-up | templates/cron-monitoring-pack.md |
| Organic landing-page report | templates/organic-landing-pages-report.md |
| Ecommerce report | templates/ecommerce-ga4-report.md |
| GSC + GA4 join report | templates/gsc-ga4-join-report.md |
This repo includes a SKILL.md file that turns it into a Claude Code skill with guided GA4 reporting and SEO growth workflows. The same workflow files can also be used by Hermes, Open Claw Agent, Codex-style coding agents, Cursor, Windsurf, Cline, or any agent that can follow markdown procedures and call MCP/direct API tools.
mkdir -p ~/.claude/skills/google-analytics
cp SKILL.md ~/.claude/skills/google-analytics/SKILL.mdThe skill will walk users through MCP server setup if it's not already configured.
If you prefer a managed solution that handles OAuth without a service account:
- Composio Rube MCP — Free tier: 1,000 requests/day. Pro: $25/month.
- See Composio pricing for details.
- MCP Server: mcp-server-google-analytics by ruchernchong
- Alternative MCP: Composio/Rube
| Tool | Repository |
|---|---|
| Google Trends | judicael-s/google-trends-skill |
| Google Analytics | This repo |
| Google Search Console | judicael-s/google-search-console-skill |
| Copywriting | judicael-s/copywriting-skill |