google-analytics-mcp AGENTS.md

AGENTS.md — Agent Operating Manual

For AI Agents (Claude Code, Cursor, Codex, Gemini, Antigravity, OpenCode, Aider) connecting to or executing google-analytics-mcp.

---

⚡ 1. Fast Install & Client Wiring (Start Here)

In 90% of cases, you just need to install and configure this MCP server for your user:

# 1-Line Universal Auto-Installer (Configures Claude Code, Cursor, Claude Desktop & Antigravity)
curl -fsSL "https://ga4.builditwithai.xyz/install" | bash

# Or launch directly via stdio:
uvx google-analytics-mcp
npx -y google-analytics-mcp

Client Config Snippet (mcp.json / claude_desktop_config.json)

{
  "mcpServers": {
    "google-analytics": {
      "command": "uvx",
      "args": ["google-analytics-mcp"],
      "env": {
        "GA4_PROPERTY_ID": "123456789",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service_account.json"
      }
    }
  }
}

---

📖 2. What This Repo Is

A production MCP server for Google Analytics 4 (GA4). It gives you direct access to the Google Analytics Data API v1beta and Admin API v1alpha.

Primary Tools Available:

• get_ga4_data: Run multi-dimensional reports with date ranges, metric totals, and server-side aggregation.
• list_accounts & list_properties: Discover all GA4 properties the credentials can access.
• get_property_metadata: Fetch exact dimension/metric schemas and custom event definitions for a property.
• run_realtime_report: Fetch live active users and 30-minute event streams.
• search_skills: Access pre-engineered analytical recipes (traffic drops, e-commerce, bot filtering).

---

👤 3. How to Handle the Human (Auth & Setup)

If credentials are not yet configured, do not fail or dump a raw Python traceback on the human. Guide them with these exact steps:

1. Ask for their 9-digit GA4 Property ID:
   • "You can find your numeric Property ID in Google Analytics under Admin → Property Settings → Property Details."
2. Ask for a Google Cloud Service Account JSON Key:
   • The human needs a Service Account with the Viewer role on their GA4 Property in Google Analytics Admin → Property Access Management.
   • Once they have the .json file, set:

     export GA4_PROPERTY_ID="123456789"
     export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service_account.json"
     

3. If Auth Fails: Call get_troubleshooting_guide(topic="setup") or get_troubleshooting_guide(topic="iam") to guide the human through permission repair.