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

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.