ga4-mcp-server

A Model Context Protocol server for Google Analytics 4. Ask your AI assistant questions like "How did organic traffic change this week?" or "Which landing pages convert worst?" and it queries GA4 for you.

Works with Claude Code, Claude Desktop, OpenAI Codex, Cursor, VS Code (Copilot), Gemini CLI, Windsurf and any other MCP client.

Built and maintained by Dien Ho of PPCBlogPro, a blog on PPC, analytics and AI marketing tools.

• 📊 Reports: standard, pivot, realtime and batched reports with filters, sorting, totals and date comparisons

• 🔎 Discovery: accounts, properties, data streams, dimension/metric catalogue, compatibility checks

• 🏷️ Friendly property lookup: say "My Blog" instead of properties/123456789

• 🧠 Context-friendly output: compact JSON records, row caps, and clear error messages with fix-it hints

• 🔐 Three ways to sign in: service account, browser sign-in, or gcloud Application Default Credentials

• ✍️ Optional admin writes: create custom dimensions/metrics and key events. Off by default.

Quick start

1. Get credentials. You need Node.js 22+ and access to a GA4 property. The fastest route for most people is a service account:

1. In Google Cloud Console, pick or create a project and enable the Google Analytics Data API and Google Analytics Admin API.

2. Go to IAM & Admin → Service Accounts, create a service account, and download a JSON key.

3. In GA4 → Admin → Property access management, add the service account's email as a Viewer.

Prefer to sign in with your own Google account? See docs/authentication.md.

2. Add the server to your client (replace the path and property):

claude mcp add ga4 \
  -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \
  -e GA4_DEFAULT_PROPERTY=123456789 \
  -- npx -y ga4-mcp-server

[mcp_servers.ga4]
command = "npx"
args = ["-y", "ga4-mcp-server"]

[mcp_servers.ga4.env]
GOOGLE_APPLICATION_CREDENTIALS = "/path/to/service-account.json"
GA4_DEFAULT_PROPERTY = "123456789"

Or: codex mcp add ga4 --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json -- npx -y ga4-mcp-server

{
  "mcpServers": {
    "ga4": {
      "command": "npx",
      "args": ["-y", "ga4-mcp-server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json",
        "GA4_DEFAULT_PROPERTY": "123456789"
      }
    }
  }
}

Same mcpServers block as Claude Desktop above.

{
  "servers": {
    "ga4": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ga4-mcp-server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

More ready-to-copy configs are in examples/. On Windows, use paths like C:\\keys\\sa.json in JSON, or 'C:\keys\sa.json' in TOML.

3. Ask away:

Which GA4 properties can I access?

Compare sessions and key events by channel for the last 28 days vs the previous 28 days.

Show the top 20 landing pages by sessions last week, with engagement rate.

How many people are on the site right now, by country?

Related MCP server: Google Analytics MCP Server

Tools

Write tools (only when GA4_MCP_ENABLE_WRITES=true): create_custom_dimension, create_custom_metric, create_key_event, archive_custom_dimension, archive_custom_metric.

Prompts: weekly_traffic_summary, top_landing_pages, channel_performance.

Full parameter reference: docs/tools.md.

Configuration

Credentials are chosen in this order: GOOGLE_APPLICATION_CREDENTIALS → saved browser sign-in token → Application Default Credentials.

Enabling write tools

Write tools change your GA4 configuration, so they're opt-in:

1. Set GA4_MCP_ENABLE_WRITES=true in the server's env.

2. Give the service account Editor on the property (or re-run npx ga4-mcp-server auth --enable-writes for browser sign-in).

Tools are annotated (readOnlyHint / destructiveHint) so clients can ask you before running anything that changes data.

Troubleshooting

Test the server interactively with the MCP Inspector: npx @modelcontextprotocol/inspector npx -y ga4-mcp-server.

Development

git clone https://github.com/dienhokhanh/ga4-mcp-server.git
cd ga4-mcp-server
npm install
npm run build
npm test          # unit + integration tests (mocked Google APIs, no credentials needed)
npm run lint
npm run inspect   # open the MCP Inspector against the local build
npm run smoke     # optional: live read-only check against your GA4 (needs credentials)

See CONTRIBUTING.md.

Privacy & security

The server runs locally and talks only to Google's Analytics APIs. Report data goes to the AI client you connect it to, so treat it as you would any analytics export. Never commit credential files. See SECURITY.md.

Author

Made by Dien Ho. I write about Google Ads, LinkedIn Ads, GA4 measurement and AI tools for marketers at PPCBlogPro.com. If this server saves you time, a ⭐ on GitHub or a visit to the blog is appreciated.

License

MIT. Not affiliated with or endorsed by Google. Google Analytics is a trademark of Google LLC.