Real-time Google Analytics 4 (GA4) Dashboard with AI Integration

This project provides a real-time dashboard for Google Analytics 4 (GA4) data, enhanced with a 3D interactive globe visualization, advanced traffic spike detection, and insightful visitor analytics. It also features a standalone Model Context Protocol (MCP) server designed to integrate with AI assistants, enabling direct querying of GA4 properties, funnels, and reports from tools like Claude Desktop, Antigravity, and Cursor.

• Real-time Analytics Dashboard: Monitor live active users, compare properties, analyze traffic sources, and track API quota usage.
• 3D Interactive Globe: Visualize live website activity across the globe in real time using Three.js.
• Spike Detection: Automatically identifies sudden traffic surges and categorizes traffic sources (referral, direct, campaign).
• Visitor Insights: Provides aggregated persona cards for new vs. returning visitors, device breakdowns, and top geographic locations.
• Standalone MCP Server: A separate server component (mcp-server/) that exposes GA4 Admin and Data API tools for MCP clients, allowing AI assistants to interact with your analytics data.
• Privacy Shield: Automatically redacts full URL parameters and query strings to prevent sensitive data leakage.
• Smart Caching & Quota Protection: Implements disk and in-memory caching with automatic background updates to preserve GA4 API quota.
• First-run Setup Page: Guides users through the initial setup process if GA4 credentials are not found.

Prerequisites:

• Node.js v18.0.0 or higher
• pnpm package manager
• A Google Cloud Platform (GCP) account with necessary permissions for the Google Analytics Data API and Google Analytics Admin API.

Setup involves:

1. Cloning the repository and installing dependencies using pnpm.
2. Creating a Google Cloud service account with appropriate permissions and downloading its JSON key file.
3. Placing the key file in the project root or configuring its path.
4. Starting the application using pnpm dev for development or pnpm start for production.

The optional MCP server can be set up and configured separately to enable AI-driven analytics queries.