GA4 MCP Server

A Model Context Protocol server that connects Claude to Google Analytics 4, enabling natural language queries of your website analytics data.

Features

• get_traffic_summary — Sessions, users, page views, bounce rate, avg session duration

• get_top_pages — Most visited pages with engagement metrics

• get_traffic_sources — Traffic breakdown by source (organic, direct, referral, etc.)

• get_user_engagement — Engaged sessions, bounce rate, screen counts per session

Related MCP server: GA4 MCP Server

Quick Start

1. Install Dependencies

npm install

2. Set Up Credentials

1. Copy the GA4 service account JSON file you downloaded to this folder:

   cp ~/Downloads/app-coaching-ga4-73c82846b5b0.json ./credentials.json

2. Create a .env file:

   cp .env.example .env

3. Update .env with your GA4 Property ID:

   GA4_CREDENTIALS_PATH=./credentials.json
   GA4_PROPERTY_ID=544866887

3. Add Service Account to GA4

In Google Analytics:

1. Go to Admin → Property Access Management

2. Click + (Add user)

3. Paste: ga4-mcp-server@app-coaching-ga4.iam.gserviceaccount.com

4. Assign Viewer role

5. Save

4. Build & Test

npm run build
npm run dev

You should see: GA4 MCP Server started

5. Test with MCP Inspector

In a new terminal:

npm run inspect

This opens an interactive tool to test the server. Try:

• Tool: get_traffic_summary

• Inputs:

  • propertyId: 544866887

  • startDate: 2026-07-01

  • endDate: 2026-07-10

Deployment Options

Option 1: Replit (Easiest)

1. Create a new Replit

2. Import from GitHub (clone this repo) or upload files

3. Set environment variables in Replit Secrets:

   • GA4_CREDENTIALS_PATH=./credentials.json

4. Upload credentials.json to Replit

5. Run: npm install && npm run build && npm run dev

6. Replit gives you a live URL

7. Connect to Claude using that URL

Option 2: Railway

1. Create a Railway project

2. Upload this repo via GitHub

3. Add credentials.json as a config file

4. Set env var: GA4_CREDENTIALS_PATH=./credentials.json

5. Deploy

6. Get the URL from Railway

7. Connect to Claude

Option 3: Local (for testing only)

Run npm run dev locally, then in Claude's MCP settings add:

{
  "name": "ga4-mcp",
  "type": "stdio",
  "command": "node",
  "args": ["dist/index.js"]
}

Usage in Claude

Once deployed, ask Claude things like:

• "What's the traffic summary for appcoaching.io for the last 7 days?"

• "Which pages on my site get the most traffic?"

• "What's driving traffic to appcoaching.io? Organic or direct?"

• "What's the engagement rate on my site?"

Claude will automatically call the appropriate GA4 tools and analyze the data.

Troubleshooting

"Credentials file not found"

• Ensure credentials.json is in the project root

• Check GA4_CREDENTIALS_PATH env var is set correctly

"Unauthorized" or "Permission denied"

• Verify the service account email is added to GA4 with Viewer role

• Check that the correct Property ID is being used (544866887)

"No data available"

• Ensure the date range has actual GA4 data

• GA4 can take 24-48 hours to start collecting data on a new property

Files

• src/index.ts — Main MCP server implementation

• package.json — Dependencies and scripts

• tsconfig.json — TypeScript configuration

• credentials.json — GA4 service account (keep secure!)

Security

Never commit credentials.json to GitHub. Add to .gitignore:

credentials.json
.env
node_modules/
dist/

The credentials file is sensitive—treat it like a password.