What it does

TL;DR for the period: headline metrics (pageviews, visitors, sessions, bounce rate, avg session duration) plus pageviews_change_pct vs the previous equivalent window (same elapsed length; its bounds are returned in previous_period as local time with offset), top page, top traffic source, bot share, and top_events: the site's own events by count (up to 10; pageview and the engagement beacon are left out; list_events has them all). Designed so a single call answers 'how did <period> go?' without chaining other tools. pageviews_change_pct is a percentage: 19.7 means +19.7%, -8.0 means -8.0% (null when the previous window had no pageviews). bounce_rate and bot_share are ratios 0–1, NOT percentages: 0.42 means 42%. A session counts only if it has at least one pageview in the period. bounce_rate is the share of those sessions with exactly one pageview and no custom event (the engagement beacon does not count). Volume metrics (pageviews / bot_share) include AI-mediated human browsing (ai_user_action — Claude/ChatGPT fetching on a user's behalf); the session metrics (sessions / bounce_rate / avg_session_duration_seconds) are browser sessions only, because server-side-ingested rows carry no session at all — pageviews still counts them, so pageviews-per-session is not a clean ratio on sites using server-side ingest. Attribution metrics (top_source) count direct browser visits only because AI-mediated traffic loses original utm/referrer tags. top_source attributes one entry per session (field `sessions`), not per pageview — don't compare it against `pageviews`. See traffic_class_breakdown for the per-class split. On privacy_mode=strict sites unique_visitors is always 0 by design (no visitor IDs computed) — judge reach by sessions there; the response's privacy_note says so too.

Example prompts

Ask Claude or any MCP client connected to mcp-analytics things like:

"How did mysite.com do last week?"
"Give me a summary for example.com, last 30 days."
"Quick overview for my main site, past 24 hours."

Claude picks get_overview automatically. An example response (formatted by Claude from the structured tool output):

67,348 pageviews (↑ 8% week-over-week), 22,104 unique visitors,
13,440 sessions. Bounce rate 41%. Average session duration 2m 14s.

Top page: /pricing (4,232 views).
Top traffic source: hacker news (1,847 sessions, a thread from
last Wednesday is driving most of it).
Bot share: 11% (mostly Googlebot and GPTBot).
Top custom events: signup_started (412), tracking_added (87),
account_created (74).

The tool returns a single object with all the headline metrics plus pageviews_change_pct versus the previous equivalent period. Designed so one tool call answers the "how did X go?" question without chaining further calls.

Pageviews and bot_share include AI-mediated human browsing (the ai_user_action traffic class: Claude or ChatGPT fetching a page on a user's behalf). Session metrics (sessions, visitors, bounce rate, session duration) count browser sessions only — an AI-mediated fetch carries no session or visitor id. Attribution metrics (the top_source field) count direct browser visits only, because AI-mediated traffic loses original UTM and referrer tags. top_source is attributed once per session, from the source the session entered on — not once per pageview. See traffic_class_breakdown for the per-class split.

Arguments

Name Type Required Description / Default
site_id string required Site identifier from list_sites (8-character base32, e.g. 'wjxayhdd').
period string optional Time window. Keywords: today, yesterday, last_N_days (N from 1 to 730: today plus the N-1 days before, e.g. last_7_days, last_28_days), last_24_hours, this_week, last_week (weeks start on Monday), this_month, last_month, this_year, last_year, last_12_months. Or a custom date range YYYY-MM-DD..YYYY-MM-DD (inclusive). Days follow the site's timezone (list_sites; echoed as `timezone` in every response).
default: last_7_days
conversion_event string optional Optional custom event name (case-sensitive, from list_events) to treat as the conversion. The overview fields are unchanged. The response gains a site-wide `conversion` block: conversion_base (units in the period), converted (how many fired the event), conversion_rate (ratio 0–1: 0.05 means 5%), `unit` and a `note` to relay. The unit depends on the site's privacy_mode: 'session' on strict and balanced sites (no identity survives UTC midnight there, so only conversions within one visit count), 'visitor' on privacy_mode=all sites (first-party cookie, so a visitor who arrives Monday and converts Thursday counts as converted, if both days are inside the period). The auto-tracked 'pageview' and 'engagement' are rejected — pick one of the site's own events. Revenue: if the event carries a numeric `revenue` property (optional `currency`), the block gains revenue_total (over the converted units), currency (null when none was sent) and revenue_events (events with a numeric value; other values are ignored). Values are as reported by the site, not verified; negative values (refunds) are summed as sent. Only three-letter currency codes count as a currency; other values are unspecified. With two or more codes nothing is converted or added across codes: revenue_total, revenue_events and the rows' revenue cover the dominant code (most distinct converting units; itself visitor-influenced) plus values without a code, and the block adds revenue_by_currency listing each code with its own count. Not available with conversion_path.
conversion_path string optional Optional goal page, the alternative to conversion_event (pass one, not both): a unit counts as converted if it has a pageview on this path anywhere in the period, so no custom event is needed and it works on past data. '/thank-you' matches that path exactly (a trailing slash on either side is ignored); a trailing * matches by prefix ('/checkout/success*'). Must start with '/'. Matched case-sensitively against the stored path, which has no query string and stores credential-like segments (long random tokens, UUIDs) as [redacted], so a goal containing one never matches. Only pageviews count: an engagement beacon or custom event on that page does not. Fields, unit (session, or visitor on privacy_mode=all sites) and the `conversion` block are as for conversion_event; the block names `path` and `match` (exact or prefix) instead of `event`. Filters narrow the units; the goal pageview counts anywhere in the period.
filters object optional Optional segment filter. All given keys must match (AND; no OR, no negation); an empty string means not set. Keys: path (exact) or path_prefix; device_type, browser, os (exact, case-sensitive); referrer_host, utm_source, utm_medium, utm_campaign (exact); channel (search, ai_assistant, social, email, paid, campaign, referral, direct; as top_referrers group_by: channel assigns it). path/path_prefix match rows: pageviews count rows on matching paths, sessions/visitors count those with at least one matching row, and bounce_rate/avg_session_duration_seconds use all rows of those sessions. referrer_host, utm_* and channel match the session's entry (its first pageview in the period) and then select every row of the matching sessions, in every privacy mode. In top_entry_pages, top_referrers, top_sources and get_overview's top_source, path/path_prefix also test the entry: path_prefix '/blog/' there means sessions that entered on /blog/. Source and device filters make every number browser-only: server-side-ingested rows (including AI-mediated ai_user_action) have no session and no device fields, so they never match; the response then adds a `filter_note`. In get_overview, bot_share is null under any key other than path/path_prefix. With conversion_event the filter narrows the units; the conversion itself still counts anywhere in the period. The applied filters are echoed back as `filters`.

How to call it directly

If you're integrating from your own code rather than a chat client, this is the JSON-RPC payload:

curl -X POST https://mcp-analytics.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_overview",
    "arguments": {
      "site_id": "abc12345"
    }
  }
}'

Token comes from /settings after you sign up. Replace any required arguments above.

Related tools

  • top_bots: Named-bot breakdown: which crawlers fetched the site, by canonical bot name (GPTBot, ClaudeBot, PerplexityBot, Googlebot, ...) with their traffic_class and hit counts.
  • get_account: Account info — email, current plan, total active sites, total_hits_this_month (across all sites), plan_limit, and api_token_first_chars (first 10 chars of the legacy API token, for identification only — not enough to authenticate).
  • top_entry_pages: Landing pages: the URL path each session entered the site on.
  • top_sources: Top UTM source/medium/campaign combinations.
  • traffic_class_breakdown: Hit counts and percentages by traffic_class for the period.