What it does

Named-bot breakdown: which crawlers fetched the site, by canonical bot name (GPTBot, ClaudeBot, PerplexityBot, Googlebot, ...) with their traffic_class and hit counts. Names match the robots.txt token where one exists; traffic identified only by infrastructure verification (e.g. reverse-DNS) without a known UA token appears under the operator name instead (e.g. "Anthropic"). Hits are aggregated across UA version churn (GPTBot/1.1 and /1.2 are one row here; top_user_agents keeps the raw-UA view). Rows are grouped by (bot_name, traffic_class), so the same name can appear twice: "GPTBot | ai_training" is traffic consistent with OpenAI's published identity signals, while "GPTBot | bot_other" is traffic that CLAIMED to be GPTBot but contradicted them (spoof) — the second row is impersonation volume, not OpenAI. Humans and unidentifiable traffic carry no bot name and are excluded — use traffic_class_breakdown for the full class-level split including users. Coverage caveat: sites tracked only via the JS snippet undercount crawlers structurally, because most crawlers (GPTBot, ClaudeBot, Googlebot, ...) do not execute JavaScript. Server-side ingest is the complete view; JS-only sites mostly see the minority of bots that run a real browser engine.

Example prompts

Ask Claude (or any MCP client connected to mcp-analytics) something like:

Use the top_bots tool on mysite.com.

The client will pick top_bots automatically based on the prompt and your account's available sites.

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
limit integer optional Maximum number of (bot_name, traffic_class) rows to return. Capped at 1000 server-side.
default: 25
filters object optional Optional: only hits on one path (path, exact) or under a prefix (path_prefix, e.g. '/blog/' for "which crawlers read the blog"); not both. No other filter keys here: bot rows have no session and mostly no device fields. 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": "top_bots",
    "arguments": {
      "site_id": "abc12345"
    }
  }
}'

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

Related tools

  • engagement_overview: Real reading time + scroll depth from the engagement beacon (fired on pagehide).
  • compare_periods: Compare a metric between two periods.
  • viewport_breakdown: Pageviews bucketed by viewport width: mobile_xs (<480), mobile (<768), tablet (<1024), desktop (<1440), desktop_xl (≥1440).
  • top_entry_pages: Landing pages: the URL path each session entered the site on.
  • color_scheme_breakdown: Share of visitors with prefers-color-scheme: dark vs light.