Analytics MCP Server
Appearance

The connection guide

Your data. Your AI. Connected.

Start with a website, connect your Google sources, and give your AI assistant the context to answer better questions.

Quickstart

  1. Sign in with Google to begin guided project setup. Signing in confirms your identity; data permission is the next step in the same flow.
  2. Choose the Google account that can access your website and approve both read-only permissions for Google Analytics and Search Console.
  3. Type your website under Find your sources by domain. The app ranks the GA4 properties (by their web streams, then by name) and Search Console properties (a domain property first) that your Google account can read, each with the reason it matched, and fills in the best pair. Or select the Analytics account, GA4 property and exact Search Console property yourself. Name the project and create it; the selected sources are verified before saving. Nothing is created or changed in Google.
  4. Add this server to your MCP client and approve it when prompted. The client appears under Connections where you can revoke it.
  5. 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 /mcp to sign in.
  • Codex: codex mcp add analytics --url <URL>, then codex 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, plus sitemaps:write only if you allow sitemap submission when approving. No API key.

Steps follow each vendor's documentation. Claude and ChatGPT connect to this server in production; for other clients, follow their own MCP documentation.

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, reconnecting Google or deleting your account ends refresh immediately. Turning sitemap submission on or off in Connections is the exception: with the same Google account and the same read-only access, AI clients stay connected.

Live analytics remain unavailable until the separate Google data connection is configured and verified. Unavailable metrics are never reported as zero.

How AI traffic is measured

AI referral reports match GA4 session sources against a versioned list of known assistant domains. They show identified sessions, their share of site sessions, landing pages, and key events. Ask your client to call get_ai_referrals to investigate the same underlying data.

This is referral measurement, not a count of AI mentions or all AI-driven visits. A visit without identifying source information may appear as Direct. Compare date ranges and hostname scope before interpreting a change. Missing data stays unavailable; a reported zero is a real zero.

Tool catalog

MCP tools
ToolReturns
get_decaying_pagesSustained declines over complete Search Console months, with monthly evidence, losing queries and section totals. Arguments: project_id; optional months (4–16), consecutive_months (1–12), min_clicks, limit and host. Missing months remain unknown; excludes partial months and respects retention.
get_fix_listRanked read-only fixes for “what should I fix?”: low CTR, competing pages, falling pages, not-found titles and optional single-URL indexing, each with evidence, a verification tool and a conservative monthly click estimate or the reason none is given. Arguments: project_id; optional days or start_date/end_date, limit (1–50), types, host, and one urls entry or a sitemap for inspection. Competing-page fixes include a provisional primary-page recommendation from existing intent/click/position evidence; verify richer value/history in get_query_detail. Missing sources are listed as unavailable, never zero.
get_page_speedOn-demand mobile/desktop Lighthouse and CrUX LCP, INP and CLS for 1–5 project URLs, or top pages by Search Console clicks. Optional urls or limit. Requires the operator PageSpeed/CrUX key, no new OAuth scope. URL field data and origin fallback are labelled; lab values never replace missing field data. Six-hour maximum memory cache, six concurrent provider requests and a 55-second report deadline; retry fewer URLs on timeout.
list_page_groupsDiscover project-local page groups and saved report filters. Arguments: project_id. On page-based reports, group selects a named group or ungrouped; saved_filter selects a named host/group/country/device preset. Groups may overlap. Ungrouped excludes their union. Country/device presets affect GA4 only. Definitions only, no report data is stored.
list_projectsOnly consented project names, setup states and GA4 hostnames. No arguments.
get_site_snapshotStart 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 (add ai_weekly, opt in, for the last seven complete days of AI referrals vs the prior seven), limit (1-20, default 5), compare_previous_period (default on) and host.
get_analytics_overviewGA4 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_breakdownGA4 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), compare_previous_period, and country, device and browser filters.
get_search_performanceSearch Console clicks, impressions, CTR and average position by query, page, country, device or date. Same optional arguments as the traffic breakdown.
get_project_statusWhat 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_pagesPages 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, country, device and browser (these narrow GA4 columns only), up to 200 rows per call with offset.
get_page_detailWhy 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_plugin_directory_trafficIncoming WordPress.org acquisition or explicitly instrumented outgoing plugin-directory clicks. Arguments: project_id, direction (incoming/outbound), plugin_slug; optional page_path, host, dates and limit up to 100. Outbound requires plugin_directory_click and a registered plugin_slug custom dimension. Missing setup is explicit; clicks do not prove destination visits or installs.
get_ai_referralsVisitors from AI assistants (ChatGPT, Perplexity, Gemini, Claude, Copilot, DeepSeek, You.com, Meta AI and others): sessions, users, new users, engaged sessions, key events, session key event rate and revenue, with their share of all sessions and the site-wide engagement baseline, by assistant, by landing page (beside organic-search sessions and Search Console clicks for the same dates) and by day, compared with the previous period or the previous year. Possible new AI sources are listed separately as unverified candidates and never counted. 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_pagesPages 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_detailOne 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 plus conservative primary-page recommendation when two or more pages compete. Recommendations list intent, click share, position/history and optional organic GA4 value; disagreement returns no_clear_winner. 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_search_valueModelled query value from visible Search Console click shares and GA4 organic landing-page revenue/key events. days 1–366 or explicit dates; limit 1–100; optional host. Missing values remain unknown; not observed query revenue.
get_opportunitiesSearch 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. mode: "striking_distance" instead ranks queries at positions 8–15 (min_position, max_position) by estimated monthly extra clicks at target_position (default 4), using the site's own 90-day CTR curve with labelled industry fallbacks for thin buckets. Same numbers as Search → Opportunities.
get_traffic_heatmapGA4 sessions, views or active users by weekday and hour (in the property's timezone), with day and hour totals and the peak hour. Optional host, country, device and browser. Same numbers as Traffic → When visitors come.
get_realtimeWho is on the site right now: GA4 active users and views in the last 30 minutes, the pages (by title) they are on and users per minute. Cached for 60 seconds. GA4 Realtime has no traffic-source or hostname dimension, so sources are not shown. Same numbers as Overview → Right now.
get_trending_queriesSearch 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_pagesPages rising, falling, new or lost, from Search Console (clicks or impressions) or GA4 (views or sessions, with titles).
explain_traffic_changeWhere a change in search clicks, impressions or GA4 sessions came from: observed contributions by page, query, channel, source group and landing page, each reconciled exactly to the total with an other/unobserved bucket, plus descriptive click effects, the first detected change date and other pages gaining for declining queries. Arguments: project_id; optional metric (clicks, impressions or sessions), days or start_date/end_date, compare (previous_period or previous_year) or compare_start_date/compare_end_date, page_url and host. Contributors missing from a period are not observed, never 0; nothing claims a cause. Same numbers as Explain this change on Trends and Page detail.
get_ga4_catalogThis property's GA4 dimensions and metrics, including custom definitions, for query_ga4_report.
query_ga4_reportFlexible 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_performanceFlexible 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.
log_changeRecords approved project change metadata (not metrics). Requires explicit changes:write consent and current owner/admin role; never edits websites or Google.
delete_changeDeletes project change metadata with explicit user approval, changes:write consent and current owner/admin role.
list_changesReads up to 200 logged changes for an approved project.
get_change_verdictLive Search Console comparison against control pages after 14 post-change days plus source lag. Descriptive, not proof of causation.
list_sitemapsSubmitted sitemaps with errors, warnings and submitted counts (Google no longer reports indexed counts reliably; use get_index_status). Read-only.
get_host_breakdownFor a project with several sites (a hub and subdomains on one GA4 property and one Search Console Domain property): one row per host with GA4 sessions, users and key events, Search Console clicks, impressions, CTR and position, and its submitted sitemaps, plus totals. Names hosts with traffic but no sitemap, a sitemap but no traffic, or sitemap errors. Arguments: project_id; optional days or start_date + end_date, include_today and limit.
get_search_featuresWhere you appear beyond web search: clicks, impressions, CTR and position per search type (web, image, video, News tab, Discover, Google News) and web results by search appearance (rich results, videos, product snippets). No data is reported as no data, never 0.
submit_sitemapThe Google write: submits a project's sitemap to Google so it is fetched again. Only for AI clients you allowed to submit sitemaps when approving them, in a workspace whose owner turned on sitemap submission (Connections). It does not request indexing of pages; once an hour per sitemap.
get_index_statusIs a page indexed? Google's URL Inspection for up to 20 URLs, or a submitted sitemap's URLs newest first (limit and offset page through all of them): indexed or not and why (reasons counted), last crawl, canonical, rich results, and a Search Console link where you can request indexing. Cached; 2,000 inspections a day per site. Same data as the Indexing page.

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 site hostnames under Projects. Every GA4 figure (by hostname) and Search Console figure (by page URL), in the dashboard and for AI clients, then covers only those hosts; connected AI clients stay connected. One project can cover a hub and all its subdomains, for example one site per country on a Search Console Domain property: use example.com and *.example.com, so new subdomains are included automatically, and ask about one site with the host argument. get_host_breakdown lists traffic, search and sitemaps per site. Until you set them, GA4 figures leave out local and test hosts such as localhost and 127.0.0.1 (builds, crawlers and scans that run the GA4 tag), and the project's setup check offers the hostname to set in one click.

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.