About this project

GA4 Dashboard & MCP is a self-hosted real-time Google Analytics 4 dashboard and an optional Model Context Protocol (MCP) server for AI assistants. ## Dashboard Features - **Real-time analytics**: Live active user monitoring, property comparison, traffic recipes, and API quota tracking. - **3D interactive globe**: Visualizes live website activity across countries worldwide using Three.js, accessible at `/globe`. - **Traffic spike detection**: Automatically detects sudden surges and classifies sources as referral, direct, or campaign. - **Visitor insights**: Persona cards for new vs. returning visitors, device breakdowns, and top geography. - **Privacy shield**: Redacts full URL parameters and query strings to prevent data leakage on dashboards. - **Smart caching**: Disk and in-memory caching layers with automatic background property metadata updates to preserve GA4 API quota. - **First-run setup page**: If no credentials are found, users are redirected to an in-browser setup flow. ## MCP Server A standalone `mcp-server/` package exposes GA4 Admin and Data API tools to MCP-compatible clients such as Claude Desktop, Antigravity, and Cursor. It operates independently of the dashboard and has its own dependencies and credentials. ## Prerequisites - Node.js v18.0.0+ - pnpm package manager - Google Cloud Platform account with a Service Account granted access to Google Analytics Data API and Admin API ## Setup Overview 1. Clone the repository and run `pnpm install`. 2. Create a Google Cloud service account, enable the required APIs, and generate a JSON key file. 3. Grant the service account Viewer access to the GA4 property and place the JSON key in the project root (or set `GA4_CREDENTIALS_PATH` in `.env`). 4. Start the app with `pnpm dev` (development) or `pnpm start` (production). 5. Optional: configure the MCP server by copying `.env.example`, pointing `GOOGLE_APPLICATION_CREDENTIALS` to a key file, and adding the server to your MCP client config. ## URLs - Main dashboard: `http://localhost:3000` - 3D globe: `http://localhost:3000/globe` - Analytics view: `http://localhost:3000/analytics` ## Testing & Building Run `pnpm test` for the Mocha unit test suite and `pnpm build` for TypeScript compilation checks. Licensed under the MIT License.