Google Analytics (GA4) MCP Server

An MCP server that connects an MCP client (Claude Desktop, etc.) to Google Analytics 4. You log into your Google account once; after that every tool reports on the GA4 properties that login can access.

Built with the official google-analytics-data and google-analytics-admin Python clients and FastMCP. Reporting, intelligence, charts, admin reads, and write/management tools (creating/updating key events, custom dimensions/metrics, and data streams).

Simpler than the Google Ads server: GA4 needs no developer token — just an OAuth client and your login.

Tools (45)

Reporting

Preset shortcuts (zero-config reports)

Accounts & configuration (admin reads)

Audience export (pull the actual users in an audience — async create → query)

Intelligence

Charts — ga4_chart_report: render a bar/line PNG of a metric by a dimension (saved to exports/).

More admin reads

Write / management ⚠️ these modify your GA4 configuration

Filtering (in ga4_run_report)

Pass dimension_filters / metric_filters — a list of conditions. Set filter_logic to AND (default) or OR; set negate: true on a condition for NOT. Each condition has field, operator, and value (or values for IN_LIST, or value + value_to for BETWEEN):

• String operators: EXACT, CONTAINS, BEGINS_WITH, ENDS_WITH, REGEXP, IN_LIST
• Numeric operators (metrics): EQUAL, LESS_THAN, LESS_EQUAL, GREATER_THAN, GREATER_EQUAL, BETWEEN

Example: country is India and sessions > 100 → dimension filter country EXACT India plus metric filter sessions GREATER_THAN 100.

More ga4_run_report options

• Sort by dimension: order_by_dimension (+ order_desc: false for ascending) — e.g. chronological by date.
• Totals: include_totals: true appends a totals row (and computes min/max).
• Metadata: results note the currency, time zone, and warn if data is sampled or thresholded.

Export

Set export_path on ga4_run_report (e.g. report.csv or report.xlsx). Bare filenames are written to an exports/ folder next to the server. CSV works out of the box; XLSX needs openpyxl (already in requirements.txt).

Setup

0. Requirements

• Python 3.9+
• A GA4 property and a Google account with at least Viewer access to it.

1. Install dependencies

cd google-analytics-mcp
python -m pip install -r requirements.txt

2. Create an OAuth client (Desktop app)

In Google Cloud Console:

1. Create/select a project.
2. APIs & Services → Library → enable both Google Analytics Data API and

Google Analytics Admin API.

1. APIs & Services → Credentials → Create credentials → OAuth client ID.
2. Application type: Desktop app. Copy the client ID and client secret.

(If the OAuth consent screen is in "Testing", add your Google account as a Test user.)

3. Log in to get your refresh token

python get_refresh_token.py

A browser opens — choose the Google account with access to your GA4 property and approve. The script writes the client ID/secret + refresh token into .env.

4. Fill in .env

cp .env.example .env   # Windows: copy .env.example .env

Required:

GOOGLE_ANALYTICS_CLIENT_ID=...        # from step 2 (also written by step 3)
GOOGLE_ANALYTICS_CLIENT_SECRET=...    # from step 2 (also written by step 3)
GOOGLE_ANALYTICS_REFRESH_TOKEN=...    # from step 3
# Optional convenience:
GOOGLE_ANALYTICS_DEFAULT_PROPERTY_ID=...   # numeric, e.g. 123456789

Find your Property ID in GA4: Admin → Property Settings → Property ID (a number like 123456789).

5. Smoke-test

python -c "import server; print('server imports OK')"

Then verify credentials end-to-end (lists your accounts/properties):

python -c "import asyncio, server; from server import AccountSummariesInput; \
print(asyncio.run(server.ga4_list_account_summaries(AccountSummariesInput())))"

6. Connect to Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) — use the absolute path to server.py:

{
  "mcpServers": {
    "google-analytics": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/google-analytics-mcp/server.py"]
    }
  }
}

The server reads .env from its own folder, so no secrets go in this config. Restart Claude Desktop.

Example prompts

• "List my GA4 accounts and properties."
• "Run a GA4 report of sessions and active users by country for the last 28 days."
• "Show screenPageViews by pagePath for last 7 days, top 20 by views."
• "What metrics and dimensions are available on property 123456789?"
• "How many active users are on the site right now, by country?"
• "Compare sessions and conversions for the last 28 days vs the prior 28 days."
• "Sessions from India only where sessions > 100, by city." (uses filters)
• "Export last month's traffic by channel to channel.xlsx."
• "Build a funnel: session_start → view_item → add_to_cart → purchase."
• "Weekly retention cohorts for the last 6 weeks."
• "Pivot sessions by country (rows) and device category (columns)."

Common GA4 names

• Metrics: activeUsers, sessions, screenPageViews, conversions,

totalRevenue, engagementRate, bounceRate, averageSessionDuration.

• Dimensions: date, country, city, deviceCategory, pagePath,

sessionDefaultChannelGroup, firstUserSource, eventName.

Use ga4_get_metadata to see everything (including custom fields) for a property.

Troubleshooting

Security

• .env holds secrets and is git-ignored — never commit it.
• Scopes: analytics.readonly (reporting + config reads), analytics.edit

(config writes — the create/update tools), and analytics.manage.users.readonly (reading access bindings). The edit scope lets the server change GA4 configuration, so treat the refresh token accordingly. After changing scopes you must re-run get_refresh_token.py and re-consent.

Project layout

google-analytics-mcp/
├── server.py             # FastMCP server + 6 tools
├── ga_client.py          # credentials, client factories, error handling
├── get_refresh_token.py  # one-time OAuth login -> refresh token
├── requirements.txt
├── .env.example          # copy to .env and fill in
├── .gitignore
└── README.md