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

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).

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

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