Documentation
Docs
Everything is read-only. Every result carries its source, range, timezone, retrieval time, and completeness.
Quickstart
- Sign in with Google to begin guided project setup. Signing in confirms your identity; data permission is the next step in the same flow.
- Choose the Google account that can access your website and approve both read-only permissions for Google Analytics and Search Console.
- Select your Analytics account, GA4 property, and exact Search Console property from the discovered lists. Name the project and create it; the selected sources are verified before saving.
- Add this server to your MCP client and approve it when prompted. The client appears under Connections where you can revoke it.
- Ask a question, such as which channels drove sessions over the last 28 days.
Connect an AI client
The MCP server URL is this site's address followed by /mcp; signed-in users can copy it from Connect AI, which has numbered steps for Claude, Claude Code, Codex, ChatGPT, Cursor, VS Code, Windsurf and Gemini CLI. In short:
- Claude (web and desktop): Customize → Connectors → Add custom connector, paste the URL, sign in when asked.
- Claude Code:
claude mcp add --transport http analytics <URL>, then run/mcpto sign in. - Codex:
codex mcp add analytics --url <URL>, thencodex mcp login analytics. - ChatGPT: developer mode, then Settings → Apps → Create with the URL and OAuth (Pro, Business, Enterprise and Edu; web only).
- Any MCP client: Streamable HTTP transport; OAuth 2.1 with dynamic client registration, PKCE (S256) and the resource indicator; scopes
projects:read analytics:read. No API key.
Steps follow each vendor's documentation; ChatGPT and Claude compatibility is not yet verified in real clients against this server. Local protocol checks do not establish compatibility.
The consent screen names the requesting client, displays its registered return address, and requires you to select projects. Access tokens expire after 10 minutes. Clients that support refresh tokens renew them automatically; each refresh token works once and is replaced on use, expires after 30 days unused, and stops after 90 days in total. Reusing an old refresh token signs the client out. Revoking a connection, changing a project's sources or deleting your account ends refresh immediately.
Live analytics remain unavailable until the separate Google data connection is configured and verified. Unavailable metrics are never reported as zero.
Tool catalog
| Tool | Returns |
|---|---|
| list_projects | Only consented project names, setup states and GA4 hostnames. No arguments. |
| get_site_snapshot | Start here. One call answers “how is the site doing?”: GA4 and Search Console totals with the previous period, top pages (titles, URLs, both sources joined), top queries, channel mix, and rising, new and falling queries, topics and pages. Arguments: project_id; optional days or start_date + end_date, sections, limit (1-20, default 5), compare_previous_period (default on) and host. |
| get_analytics_overview | GA4 and Search Console totals and daily rows, each with its own range, timezone and warnings. Arguments: project_id; optional days (7, 28 or 90; default 7) and compare_previous_period. |
| get_traffic_breakdown | GA4 sessions, active users, engaged sessions, engagement rate, key events and revenue by channel, source/medium, referrer (exact referring domain), source group (AI assistants, Search, Social, Email, Referral, Paid and other, Direct / unknown; rules in the docs), landing page, country, device or date. Arguments: project_id; optional breakdown, days (7, 28 or 90) or start_date + end_date (YYYY-MM-DD, at most 366 days), limit (1-100) and compare_previous_period. |
| get_search_performance | Search Console clicks, impressions, CTR and average position by query, page, country, device or date. Same optional arguments as the traffic breakdown. |
| get_project_status | What the project can see: each source's state, last date with data, Search Console's first non-final date, limits and the remaining Google request budget. |
| get_top_pages | Pages with titles and URLs: GA4 views, sessions, users, new users, engagement, key events and session key event rate joined with Search Console clicks, impressions, CTR and position by host and path, with match statistics. scope=landing_pages matches GA4's Landing page report and adds each page's source mix (top source / medium, % AI assistants, % organic search). Search, sort (a rate sort leaves out pages under min_sessions, default 10), comparison, optional host, up to 200 rows per call with offset. |
| get_page_detail | Why one page gets traffic and whether it converts: views, sessions, users, new users, engagement, key events and session key event rate; channels, source/medium, referring sources (marked when they are AI assistants) and an AI assistants summary, countries, devices, entrances, daily trend and the Search Console queries for that page with change versus the previous period. Takes a URL on the project's site or a path; the URL is never fetched. |
| get_ai_referrals | Visitors from AI assistants (ChatGPT, Perplexity, Gemini, Claude, Copilot, DeepSeek, You.com, Meta AI and others): sessions, users, new users, engaged sessions, key events and session key event rate, with their share of all sessions, by assistant, by landing page and by day, compared with the previous period. Matching uses GA4's session source against a versioned domain list that the result includes. Arguments: project_id; optional days or start_date + end_date, group_by (source, landing_page or date), limit, compare_previous_period (default on) and host. Same numbers as the AI referrals page. |
| get_broken_pages | Pages with a not-found title ("Page not found", "404"…) that still get visits: views, sessions, entrances, the pages that link to them (internal links marked) and the session sources, so you can fix links or add redirects. Same numbers as Pages → Broken pages. |
| get_query_detail | One search query: every page that ranks for it with clicks, impressions, CTR, average position and share of the query's impressions, the daily trend, the previous period, and a cannibalisation flag when two or more pages each get at least 10% of its impressions. Arguments: project_id, query; optional days or start_date + end_date, compare_previous_period (default on) and limit. Same numbers as Search → query detail. |
| get_opportunities | Search queries worth working on: at least min_impressions (default 100), average position 5–20 and a CTR below half the typical CTR for that position, ranked by the estimated extra clicks; plus cannibalised queries. The rules and typical-CTR table are in the result. Same numbers as Search → Opportunities. |
| get_trending_queries | Search queries that are rising, falling, new or lost versus the previous equal period, with minimum-volume thresholds and heuristic topics (shared words and phrases). |
| get_trending_pages | Pages rising, falling, new or lost, from Search Console (clicks or impressions) or GA4 (views or sessions, with titles). |
| get_ga4_catalog | This property's GA4 dimensions and metrics, including custom definitions, for query_ga4_report. |
| query_ga4_report | Flexible GA4 report: up to 9 dimensions and 10 metrics checked against the property's catalogue and Google's compatibility check, filters (match, regex, in-list, numeric, between, empty), order, comparison range, up to 1,000 rows with offset. |
| query_search_performance | Flexible Search Console report: query, page, country, device, search appearance or date; web, image, video, news, Discover or Google News; final or fresh data; regex filters; up to 1,000 rows with start_row. |
| list_sitemaps | Submitted sitemaps with errors, warnings and submitted vs indexed counts. Read-only. |
AI clients do best by calling get_site_snapshot first and drilling down only where it points: get_page_detail for one page, the trending tools for full lists, the flexible queries for anything else. The server also offers a tool guide and limits as MCP resources, and two prompts (weekly content report, why did traffic change).
If a GA4 property records several sites (for example a marketing site and an app backend), set the project's GA4 hostnames under Projects. Every GA4 figure, in the dashboard and for AI clients, then covers only those hosts; connected AI clients stay connected.
Limits
- Free plan: one project, one GA4 property, one Search Console site.
- MCP report tools take a project_id plus a number of days or a custom start_date and end_date of at most 366 days. Breakdowns return up to 100 top rows; pages up to 200 per call and flexible queries up to 1,000 per call, with offset or start_row pagination.
- Google requests (not tool calls) are budgeted per workspace: 240 a minute and 3,000 a day on Free (30,000 on Pro). Cached reports cost only their access checks. Reports for ranges that ended at least 3 days ago are cached for an hour (GA4) or six hours (Search Console final data); access is still checked live on every call.
- Search Console data lags 2–3 days, keeps 16 months, and may be marked incomplete.
- Pro is granted by manual review. There is no billing.
Privacy
- Scopes requested: analytics.readonly and webmasters.readonly. Nothing can be written to Google.
- Disconnecting revokes Google tokens and clears cached reports.
- Deleting your account removes projects, grants, and requests.
- Raw reports are not used to train models.
Troubleshooting
- Permission error: the Google account lacks access to the property or site. Reconnect with the right account.
- Partial consent: one scope was unchecked on the consent screen. Reconnect and tick both.
- No data in range: a real empty result. Widen the range or check the property ID.
- Client cannot connect: revoke it under Connections and approve again.
- Cannot sign in: use Google account recovery.