analytics-selfhosted-mcp

Unofficial / community project. This is not an official Google product.
Official Google Analytics MCP (local stdio only):
googleanalytics/google-analytics-mcp (PyPI: analytics-mcp).

Self-host the same GA Admin/Data tools over Streamable HTTP on Modal, so clients that only accept a public URL (Cursor remote MCP, agents, etc.) can call Google Analytics with an API key — plus token-efficient report compaction that upstream does not ship.

When to use official: one machine, Cursor/Claude Desktop via command + stdio.
When to use this: you need a URL-addressable Analytics MCP.

ClickUp App Center auth works but tools do not load yet (client never calls tools/list). Details: docs/CLICKUP_ISSUE.md.

Quick path (what “done” looks like)

Do not skip the Done when checks — each later step depends on the previous one.

Related MCP server: analytics-mcp

Use cases and suggested queries

Ask these in Cursor (or any MCP client) after step 7. Complexity increases downward.

Level 1 — Connectivity & inventory

Pass: you get real account/property names (not 401 / empty / credential errors).

Level 2 — Simple reporting

Pass: summary includes a report_id (compact) or clear row values; numbers look plausible vs GA UI.

Level 3 — Metadata & quality

Pass: tool returns structured data (or a clear empty list if none configured).

Level 4 — Funnels, conversions, large data

Pass: compact path returns small summary + report_id; paging returns slices; discard succeeds.

Level 5 — Analysis workflows

Pass: answers cite tool results (property id, dates, metrics), not invented UI screenshots.

Step-by-step setup

Step 0 — Prerequisites

Install:

# Python 3.12+ recommended
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install modal
modal setup   # browser login

In Google Cloud (same project you will put in .env):

1. Enable Google Analytics Admin API

2. Enable Google Analytics Data API

Done when:

uv --version          # prints a version
modal --version       # prints a version
modal profile current # shows your logged-in profile / workspace

If it fails: re-run modal setup; confirm the GCP project has billing/API enablement as required by Google.

Step 1 — Clone and create .env

git clone https://github.com/YOUR_GITHUB_USER/analytics-selfhosted-mcp.git
cd analytics-selfhosted-mcp
cp .env.example .env

Edit .env:

GOOGLE_PROJECT_ID=your-gcp-project-id
MCP_API_KEY=$(openssl rand -hex 24)
ANALYTICS_MCP_API_KEY=$MCP_API_KEY   # must match MCP_API_KEY

Done when:

set -a && source .env && set +a
test -n "$GOOGLE_PROJECT_ID" && test -n "$MCP_API_KEY" && test "$MCP_API_KEY" = "$ANALYTICS_MCP_API_KEY" && echo "env ok"
git check-ignore -v .env   # must show .gitignore rule

If it fails: keys empty or mismatched — fix .env. If .env is not ignored, stop and fix .gitignore before any commit.

Step 2 — Google credentials (service account recommended)

1. GCP → IAM → Service Accounts → create SA in GOOGLE_PROJECT_ID

2. Create a JSON key → save as e.g. ~/secrets/ga-mcp-sa.json (outside this repo)

3. GA Admin → Account/Property access → add SA email as Viewer on every property you need

Done when (local check):

export GOOGLE_APPLICATION_CREDENTIALS=~/secrets/ga-mcp-sa.json
# Optional: quick Admin API sanity via gcloud / any GA client you prefer.
# On Modal, success is verified in Step 6 (get_account_summaries).
ls -la "$GOOGLE_APPLICATION_CREDENTIALS"   # file exists, contains "client_email"

If it fails later with empty accounts / 403: SA missing Viewer on the GA property, or wrong JSON in the Modal secret.

Temporary alternative: user ADC (gcloud auth application-default login with Analytics readonly scopes). Prefer SA for cloud.

Step 3 — Modal secret

Secret name must be exactly analytics-mcp-creds:

set -a && source .env && set +a

modal secret create analytics-mcp-creds \
  MCP_API_KEY="$MCP_API_KEY" \
  GOOGLE_PROJECT_ID="$GOOGLE_PROJECT_ID" \
  GOOGLE_APPLICATION_CREDENTIALS_JSON="$(cat ~/secrets/ga-mcp-sa.json)" \
  --force

Done when:

modal secret list | grep analytics-mcp-creds

If it fails: path to JSON wrong; or JSON not pasted as file contents (must start with {, not a filesystem path string).

Step 4 — Deploy

modal deploy modal_ga_mcp.py

Note the printed web URL:

https://YOUR_WORKSPACE--analytics-mcp-ga-web.modal.run

(The Modal app id remains analytics-mcp-ga so existing deployments keep a stable hostname.)

Done when:

curl -sS "https://YOUR_WORKSPACE--analytics-mcp-ga-web.modal.run/healthz"
# Expect: {"status":"ok","app":"analytics-mcp-ga"}

If it fails: check Modal dashboard logs for import/boot errors; confirm secret name spelling.

Optional: set in .env:

MODAL_MCP_URL=https://YOUR_WORKSPACE--analytics-mcp-ga-web.modal.run/mcp

Step 5 — Verify MCP protocol (auth + tools)

set -a && source .env && set +a
URL="${MODAL_MCP_URL:-https://YOUR_WORKSPACE--analytics-mcp-ga-web.modal.run/mcp}"
KEY="$MCP_API_KEY"

curl -sS -D /tmp/mcp.hdr -o /tmp/mcp.init -X POST "$URL" \
  -H "Authorization: $KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"setup","version":"0"}}}'

# Expect HTTP 200 and a mcp-session-id header
grep -i mcp-session-id /tmp/mcp.hdr
cat /tmp/mcp.init

SID=$(awk 'BEGIN{IGNORECASE=1} /^mcp-session-id:/{print $2}' /tmp/mcp.hdr | tr -d '\r')

curl -sS -X POST "$URL" \
  -H "Authorization: $KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "mcp-session-id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | tee /tmp/mcp.tools

Done when: /tmp/mcp.tools lists 15 tools, including:

• Upstream (9): get_account_summaries, list_google_ads_links, get_property_details, list_property_annotations, get_custom_dimensions_and_metrics, run_report, run_realtime_report, run_funnel_report, run_conversions_report

• Host (6): ping, run_report_compact, get_report_rows, get_report_summary, get_report_full, discard_report

If it fails:

Step 6 — Verify Google Analytics access

set -a && source .env && set +a
export MODAL_MCP_URL="${MODAL_MCP_URL:-https://YOUR_WORKSPACE--analytics-mcp-ga-web.modal.run/mcp}"

modal run modal_ga_mcp.py::test_account_summaries
# Then pick a property id from the output:
modal run modal_ga_mcp.py::test_run_report --property-id=YOUR_GA4_PROPERTY_ID
modal run modal_ga_mcp.py::test_run_report_compact --property-id=YOUR_GA4_PROPERTY_ID

Done when: account summaries show your properties; report/compact tests print row data / a report_id.

If it fails:

Step 7 — Connect Cursor

cp .cursor/mcp.json.example .cursor/mcp.json
# Edit url → your Modal /mcp URL

{
  "mcpServers": {
    "analytics-selfhosted-mcp": {
      "url": "https://YOUR_WORKSPACE--analytics-mcp-ga-web.modal.run/mcp",
      "headers": {
        "x-api-key": "${env:ANALYTICS_MCP_API_KEY}"
      }
    }
  }
}

Cursor does not load project .env for remote MCP headers. Export before launching Cursor:

set -a && source .env && set +a
export ANALYTICS_MCP_API_KEY
# launch Cursor from this shell, or put ANALYTICS_MCP_API_KEY in your shell profile / direnv

Reload MCP servers in Cursor.

Done when: MCP shows tools; in chat: “Call ping” → pong.

If it fails:

Some hosts prefer Authorization instead of x-api-key (raw key or Bearer …). This server accepts both.

How data moves (read once)

Client  --tools/call-->  Modal MCP  --GA API-->  Google
                ^                         |
                +---- tool result JSON ---+

Tool results still enter the model context. Large run_report payloads can blow the context window.

Prefer for big reports:

1. run_report_compact → summary + report_id (full payload stored server-side)

2. get_report_rows → page rows

3. discard_report when finished

4. get_report_full(..., confirm=true) only if you intentionally want everything in-context

Troubleshooting (cheat sheet)

Still stuck: Modal function logs for analytics-mcp-ga / web, plus the curl transcript from Step 5.

Security

Never commit: .env, ADC/SA JSON, client_secret_*.json, .cursor/mcp.json.

Checklist: docs/PUBLISHING.md.

openssl rand -hex 24   # rotate MCP_API_KEY → update .env + Modal secret + Cursor

Repo layout

Optional ping-only: modal deploy modal_mcp_ping.py (same analytics-mcp-creds secret).

License

MIT. GA tool callables come from Google’s analytics-mcp; this repo hosts them remotely and adds compaction. Not affiliated with Google.