Rybbit MCP Server

[!NOTE] Rybbit now ships an official MCP server — a hosted, remote endpoint built into Rybbit itself with OAuth and scoped API-key support. This package offers full feature parity with it, plus extra tools it doesn't have (composite summaries, period comparison, batch event ingestion, ~20 additional read endpoints) and a local stdio transport for clients without remote MCP/OAuth support. See How this compares to the official Rybbit MCP.

An MCP (Model Context Protocol) server for the Rybbit Analytics API. It gives MCP-compatible AI assistants access to your Rybbit Analytics data and management capabilities, allowing you to query traffic, sessions, events, users, goals, funnels, performance, errors, and more using natural language. Ask questions like, "How many people visited last week, and what pages did they view?" and get detailed answers.

Installation

No installation required! Use npx to run directly.

Or install globally:

npm install -g rybbit-mcp-server

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | RYBBIT_API_KEY | Yes | — | Your Rybbit API key | | RYBBIT_URL | No | https://app.rybbit.io | Base URL for the Rybbit API (for self-hosted instances) | | RYBBIT_CACHE_TTL | No | 60 | Seconds to cache GET responses in memory (0 disables; live visitor counts are never cached) | | RYBBIT_READ_ONLY | No | off | Set to 1 or true to run read-only: all 18 write tools (goal/funnel/site/team create-update-delete, member management, user identify/traits/delete, event tracking) are hidden from the tool list and rejected if called |

Getting an API Key

1. Navigate to Settings → Account in your Rybbit dashboard
2. Go to the API Keys section
3. Create a key with a custom name
4. Copy it immediately (it won't be shown again)

How this compares to the official Rybbit MCP

Compared against the official MCP v0.3.0 (Rybbit v2.7.0, July 2026).

| Capability | Official MCP | This package | |---|:---:|:---:| | Analytics reads (overview, timeseries, breakdowns, live, retention, journeys, web vitals, errors) | ✅ | ✅ | | Sessions, events, users (raw data reads) | ✅ | ✅ | | Goals & funnels (read, analyze, CRUD) | ✅ | ✅ | | Sites & organizations (CRUD, members) | ✅ | ✅ | | Raw read-only ClickHouse SQL (run_query + schema) | ✅ | ✅ | | User identify / traits / GDPR delete | ✅ | ✅ | | Teams & member site-access management | ✅ | ✅ | | Extra read tools (goal sessions, funnel step sessions, performance timeseries & by-dimension, error events & timeseries, session locations, user session counts, event properties, outbound links) | ❌ | ✅ | | Event ingestion (rybbit_track_event) | ❌ | ✅ | | Batch event ingestion (rybbit_track_events, 1–50 per call) | ❌ | ✅ | | Composite digest (rybbit_get_site_summary) | ❌ | ✅ | | Period-over-period comparison (rybbit_compare_periods) | ❌ | ✅ | | Response caching + rate-limit awareness | ❌ | ✅ | | Read-only mode via env flag | ❌ | ✅ | | Local stdio transport (no remote MCP/OAuth support needed) | ❌ | ✅ | | Hosted remote endpoint (nothing to run locally) | ✅ | ❌ | | OAuth authorization flow | ✅ | ❌ |

Both authenticate with the same Rybbit API keys and hit the same public REST API, so scoped keys (resource:action permissions) work identically: reads need the matching :read scope, writes need :write (write implies read), and destructive operations additionally require org admin/owner role. rybbit_run_query needs sql:read; server-side event ingestion is marked trusted with ingest:write. The official server can approximate read-only operation with a scoped API key; this package's RYBBIT_READ_ONLY flag works with any key and composes with scoped keys.

Usage

With Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "rybbit": {
      "command": "npx",
      "args": ["rybbit-mcp-server"],
      "env": {
        "RYBBIT_API_KEY": "your_api_key_here"
      }
    }
  }
}

For self-hosted Rybbit instances, add the RYBBIT_URL environment variable:

{
  "mcpServers": {
    "rybbit": {
      "command": "npx",
      "args": ["rybbit-mcp-server"],
      "env": {
        "RYBBIT_API_KEY": "your_api_key_here",
        "RYBBIT_URL": "https://your-rybbit-instance.com"
      }
    }
  }
}

With Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "rybbit": {
      "command": "npx",
      "args": ["rybbit-mcp-server"],
      "env": {
        "RYBBIT_API_KEY": "your_api_key_here",
        "RYBBIT_URL": "https://your-rybbit-instance.com"
      }
    }
  }
}

Standalone

npx rybbit-mcp-server

# Or if installed globally:
rybbit-mcp-server

Example Questions

| You ask... | Tools used | |---|---| | "How many people visited last week, and what pages did they view?" | rybbit_get_site_summary | | "Show the daily traffic trend this month" | rybbit_get_overview_timeseries | | "Where is my traffic coming from?" | rybbit_get_metric (referrer, country, utm_source) | | "Who are my most active users, and what did they do?" | rybbit_get_users → rybbit_get_user_sessions | | "Trace one visitor's journey" | rybbit_get_user_sessions → rybbit_get_session_details | | "How many people are on the site right now?" | rybbit_get_live_visitors | | "Is the site healthy?" | rybbit_get_performance_overview + rybbit_get_error_names | | "How is my signup funnel converting?" | rybbit_get_funnels → rybbit_analyze_funnel | | "What are the most common paths through my site?" | rybbit_get_journeys | | "Are users coming back?" | rybbit_get_retention |

Available Tools

Overview & Metrics

• rybbit_get_overview - Get high-level analytics (sessions, pageviews, users, bounce rate)
• rybbit_get_overview_timeseries - Get time-series analytics data
• rybbit_get_metric - Get dimensional breakdown by parameter (browser, country, etc.)
• rybbit_get_live_visitors - Get count of currently active visitors

Sessions

• rybbit_get_sessions - Get paginated list of sessions
• rybbit_get_session_details - Get detailed session info with events
• rybbit_get_session_locations - Get session locations for map visualization

Events

• rybbit_get_events - Get paginated list of events (supports sinceTimestamp/beforeTimestamp cursors)
• rybbit_get_event_names - Get unique event names with counts
• rybbit_get_event_properties - Get properties for a specific event
• rybbit_get_outbound_links - Get outbound link clicks

Users

• rybbit_get_users - Get paginated list of users
• rybbit_get_user_sessions - Get sessions for a specific user
• rybbit_get_user_session_count - Get daily session count for a user
• rybbit_get_user_info - Get detailed user profile

SQL (Raw Data)

• rybbit_run_query - Run read-only ClickHouse SQL against your events (SELECT-only, max 1,000 rows, 10s cap)
• rybbit_get_query_schema - Get the events-table column schema for writing queries

Users (management)

• rybbit_identify_user - Link an anonymous visitor to a user ID and merge traits
• rybbit_update_user_traits - Replace a user's profile traits (wholesale replacement)
• rybbit_delete_user - Permanently erase a user and all their data (GDPR, irreversible)

Goals

• rybbit_get_goals - Get goals with conversion metrics
• rybbit_get_goal_sessions - Get sessions that completed a goal
• rybbit_create_goal - Create a new goal (path or event-based)
• rybbit_update_goal - Update goal configuration
• rybbit_delete_goal - Delete a goal

Funnels

• rybbit_get_funnels - Get saved funnels
• rybbit_analyze_funnel - Analyze step-by-step conversion
• rybbit_get_funnel_step_sessions - Get sessions at a funnel step
• rybbit_create_funnel - Create a new funnel
• rybbit_delete_funnel - Delete a funnel

Performance (Core Web Vitals)

• rybbit_get_performance_overview - Get LCP, CLS, INP, FCP, TTFB metrics
• rybbit_get_performance_timeseries - Get performance trends over time
• rybbit_get_performance_by_dimension - Get performance by pathname, country, etc.

Error Tracking

• rybbit_get_error_names - Get unique errors with counts
• rybbit_get_error_events - Get error occurrences with stack traces
• rybbit_get_error_timeseries - Get error trends over time

Retention & Journeys

• rybbit_get_retention - Get cohort-based retention analysis
• rybbit_get_journeys - Get common user navigation paths

Organizations & Sites

• rybbit_get_organizations - Get your organizations
• rybbit_get_organization_members - Get organization members
• rybbit_add_organization_member - Add a member to an organization
• rybbit_create_site - Create a new site
• rybbit_get_site - Get site details
• rybbit_update_site - Update site configuration
• rybbit_delete_site - Delete a site
• rybbit_get_excluded_ips - Get IPs excluded from tracking
• rybbit_get_excluded_countries - Get country codes excluded from tracking
• rybbit_get_private_link_config - Get private-link sharing config (org admin only)

Teams

• rybbit_get_teams - List teams with members and site assignments
• rybbit_create_team - Create a team with optional members and sites
• rybbit_update_team - Update a team (member/site lists replaced wholesale)
• rybbit_delete_team - Delete a team
• rybbit_update_member_site_access - Restrict a member to specific sites

Event Tracking

• rybbit_track_event - Send tracking events (pageview, custom, performance, error, outbound)

Composite & Batch

• rybbit_get_site_summary - One-call digest: overview + top pages/referrers/countries/devices/events + live count (~7 API requests)
• rybbit_compare_periods - Compare overview metrics vs the equal-length preceding period with deltas
• rybbit_track_events - Send 1-50 tracking events in one call with per-event results

Common Parameters

Time Parameters

Most analytics tools accept time parameters:

• startDate / endDate - Date range in YYYY-MM-DD format
• timeZone - IANA timezone (e.g., "America/New_York")
• pastMinutesStart / pastMinutesEnd - Relative time range in minutes

Filters

Filter data using JSON array format:

[
  {
    "parameter": "country",
    "type": "equals",
    "value": ["US"]
  }
]

Filter types: equals, not_equals, contains, not_contains, regex, not_regex, greater_than, less_than

Available parameters: browser, operating_system, device_type, country, region, city, pathname, page_title, hostname, querystring, referrer, utm_source, utm_medium, utm_campaign, user_id, event_name

Rate Limits

The Rybbit API has a rate limit of 500 requests per 10 minutes per API key.

License

MIT