Google Analytics MCP Server

This server provides access to Google Analytics 4 data through both MCP (Model Context Protocol) and REST endpoints. It allows you to fetch various analytics metrics for specific URLs, including page views, engagement metrics, traffic sources, and conversions.

At a glance — A small, focused MCP server that exposes Google Analytics 4 data to AI agents. Built on the official @modelcontextprotocol/sdk (Streamable HTTP transport) over Express, with the same tool surface available as plain REST endpoints for non-MCP clients. Five tools: getUrlAnalytics, getUrlEngagement, getUrlSourceTraffic, getUrlConversions, getUrlPageViews.

What this repo demonstrates

• A real MCP server — uses the actual @modelcontextprotocol/sdk (McpServer + StreamableHTTPServerTransport), not a sketch. Same tools available via MCP and REST, no schema duplication.
• GA4 Data API integration — BetaAnalyticsDataClient from @google-analytics/data with service-account auth, and a small URL-path → GA filter abstraction so callers ask "what happened on /about" rather than "give me a pagePathPlusQueryString filter expression."
• Useful response shape — every endpoint returns the headline numbers plus a timeBreakdown.daily and timeBreakdown.monthly series so an agent can answer "how did that change over the period?" without a follow-up call.
• Honest dev experience — Zod-validated env, structured debug logging behind a DEBUG flag, Jest tests, an mcp-inspector-driven smoke script (pnpm test:mcp), and a parallel REST smoke script (pnpm test:rest).

Quickstart

pnpm install
cp .env.example .env             # fill in GA_PROPERTY_ID + path to service-account JSON
pnpm dev                         # http://localhost:3001
pnpm test:rest                   # smoke-test the REST endpoints

Full setup, endpoint reference, response schema, and error handling are documented below.

Setup

1. Install dependencies:

pnpm install

2. Set up environment variables in .env:

GA_PROPERTY_ID=your_ga4_property_id
GOOGLE_APPLICATION_CREDENTIALS=path/to/your/credentials.json
PORT=3001 # optional, defaults to 3001
DEBUG=true # optional, for debug logging

Available Endpoints

The server provides two ways to access analytics data:

1. MCP Endpoint

The MCP endpoint is available at /mcp and supports the Model Context Protocol for streaming communication.

Example using the MCP client:

import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

// Initialize MCP client
const transport = new StreamableHTTPClientTransport({
  url: "http://localhost:3001/mcp"
});
const client = new McpClient();
await client.connect(transport);

// Example: Get URL analytics
const response = await client.callTool("getUrlAnalytics", {
  url: "/about",
  timeframe: "this month",
  trafficSourceLimit: 5
});

console.log(JSON.parse(response.content[0].text));

2. REST Endpoints

The server also provides traditional REST endpoints for simpler integration:

Get URL Analytics

// Get comprehensive analytics for a URL
const response = await fetch(
  "http://localhost:3001/getUrlAnalytics?url=/about&timeframe=this+month&trafficSourceLimit=5",
  {
    headers: {
      'Accept': 'application/json'
    }
  }
);
const data = await response.json();

Get URL Engagement

// Get engagement metrics
const response = await fetch(
  "http://localhost:3001/getUrlEngagement?url=/about&timeframe=last+week",
  {
    headers: {
      'Accept': 'application/json'
    }
  }
);
const data = await response.json();

Get Traffic Sources

// Get traffic sources
const response = await fetch(
  "http

... [View full README on GitHub](https://github.com/spindle79/ga4-mcp-server#readme)