Skip to main content
Glama
rybbit-mcp

rybbit-mcp

by nks-hub

@nks-hub/rybbit-mcp

Build Status npm version Node.js TypeScript MCP SDK License: MIT

MCP server for Rybbit Analytics. Claude Code and other MCP clients use it to query statistics, errors, users, sessions, funnels, goals and performance metrics.

Features

  • 🧰 32 analytics tools - Overview, metrics, sessions, users, events, errors, performance, funnels, goals, journeys and site management

  • 🔐 Authentication - API key (recommended) or email and password

  • 🔍 Filtering - Filter by 22 dimensions (browser, country, UTM, page, device, etc.) with 8 comparison types

  • 📅 Time ranges - Date ranges (YYYY-MM-DD) or relative time (pastMinutesStart)

  • 📈 Time series - Bucket size from one minute to one year

  • 📄 Pagination - page and limit parameters for large result sets

  • ✂️ Response truncation - Cuts responses at 25k characters so they fit the model context

  • 💡 Error messages - Tell the model what to try next, e.g. narrow the date range or call rybbit_list_sites for valid IDs

Related MCP server: GA4 MCP Server

Requirements

  • Node.js: 18+

  • Rybbit Analytics: Self-hosted or cloud instance

Installation

Configure your MCP client to run the package via npx:

{
  "mcpServers": {
    "rybbit": {
      "command": "npx",
      "args": ["-y", "@nks-hub/rybbit-mcp"],
      "env": {
        "RYBBIT_URL": "https://your-rybbit-instance.com",
        "RYBBIT_API_KEY": "your-api-key"
      }
    }
  }
}

Add this to your ~/.claude/settings.json or project .claude/settings.json.

CLI shorthand:

claude mcp add rybbit -e RYBBIT_URL=https://your-instance.com -e RYBBIT_API_KEY=your-key -- npx -y @nks-hub/rybbit-mcp

From source

For development or contributing:

git clone https://github.com/nks-hub/rybbit-mcp.git
cd rybbit-mcp
npm install && npm run build

Then point your MCP config to the local build:

{
  "mcpServers": {
    "rybbit": {
      "command": "node",
      "args": ["path/to/rybbit-mcp/build/index.js"],
      "env": {
        "RYBBIT_URL": "https://your-rybbit-instance.com",
        "RYBBIT_API_KEY": "your-api-key"
      }
    }
  }
}

Usage

Once the server is configured, Claude Code can answer questions such as:

  • "How many users visited the site today?"

  • "Show me the top pages by bounce rate this week"

  • "What errors occurred in the last hour?"

  • "Show user journey from homepage to checkout"

  • "Compare browser usage between mobile and desktop"

Authentication

Method

Environment Variables

Use Case

API key

RYBBIT_API_KEY

Recommended for production

Email/password

RYBBIT_EMAIL, RYBBIT_PASSWORD

Development/testing

Both require RYBBIT_URL pointing to your Rybbit instance.

Tools (32)

Configuration and site management

Tool

Description

rybbit_get_config

Get server version and configuration

rybbit_list_sites

List all sites and organizations

rybbit_create_site

Create a new site (type: web or mobile; legacy alias app maps to mobile; mobile sites have bot filtering turned off)

rybbit_delete_site

Delete a site permanently

rybbit_get_site_id

Look up site ID by domain name

rybbit_update_site_config

Update site tracking config (IP, errors, replay, etc.)

Real-time and overview

Tool

Description

rybbit_live_users

Current active users count

rybbit_get_overview

Aggregated metrics (sessions, pageviews, users, bounce rate, duration)

rybbit_get_overview_timeseries

Metrics as time-series with configurable buckets

rybbit_get_session_locations

Geographic session data with coordinates for map visualization

Metrics and dimensions

Tool

Description

rybbit_get_metric

Breakdown by dimension (browser, OS, country, page, UTM, etc.)

rybbit_get_retention

User retention cohort analysis

Sessions

Tool

Description

rybbit_list_sessions

Session list with filtering by IP, identified users, min duration, and pagination

rybbit_get_session

Full session detail with events and user traits

Users

Tool

Description

rybbit_list_users

Users with search, sort (first/last seen, pageviews, sessions, duration), and identified-only filter

rybbit_get_user

User detail with traits and activity

rybbit_get_user_traits

Trait keys, values, or find users by trait

rybbit_get_user_event_breakdown

Per-user event count breakdown

Events

Tool

Description

rybbit_list_events

Raw event records with filtering

rybbit_get_event_names

Custom event names and counts

rybbit_get_event_properties

Property breakdowns per event

rybbit_get_event_timeseries

Event count trends over time with configurable buckets

rybbit_get_outbound_links

Outbound link clicks with URLs and counts

Errors

Tool

Description

rybbit_get_errors

Error types/counts, individual instances, or timeseries for a specific error

Performance (Web Vitals)

Tool

Description

rybbit_get_performance

Core Web Vitals (LCP, CLS, INP, FCP, TTFB) with percentiles

rybbit_get_performance_timeseries

Web Vitals trends over time

Funnels and goals

Tool

Description

rybbit_list_funnels

Saved funnels with step definitions

rybbit_analyze_funnel

Ad-hoc funnel analysis with custom steps

rybbit_get_funnel_step_sessions

Sessions that reached or dropped off at a funnel step

rybbit_list_goals

Goals with conversion metrics

rybbit_get_goal_sessions

Sessions that completed a specific goal

Journeys

Tool

Description

rybbit_get_journeys

User navigation path analysis

Common parameters

All analytics tools support these optional parameters:

Parameter

Type

Description

siteId

string

Site identifier (required)

startDate

string

Start date YYYY-MM-DD

endDate

string

End date YYYY-MM-DD

timeZone

string

IANA timezone (e.g., Europe/Prague)

filters

array

Filter array [{parameter, type, value[]}]

pastMinutesStart

number

Minutes ago (alternative to date range)

Filter parameters

browser, operating_system, language, country, region, city, device_type, referrer, hostname, pathname, page_title, querystring, event_name, channel, utm_source, utm_medium, utm_campaign, utm_term, utm_content, entry_page, exit_page, user_id

Filter types

equals, not_equals, contains, not_contains, regex, not_regex, greater_than, less_than

Time buckets

minute, five_minutes, ten_minutes, fifteen_minutes, hour, day, week, month, year

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Type checking
npx tsc --noEmit

Contributing

Contributions are welcome! For major changes, please open an issue first.

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'feat: description')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Support

License

MIT License — see LICENSE for details.


Available Tools

43 tools
rybbit_analyze_funnelAnalyze FunnelB
Read-onlyIdempotent

Analyze a custom funnel by defining steps (page visits or events). Returns visitor counts and drop-off rates at each step.

Inputs: steps (required), siteId (required), endDate, filters, +4 more. Returns: steps

rybbit_create_funnelCreate FunnelA

Save a new named funnel definition. Steps are evaluated in order. Pass an existing funnel report ID to overwrite that funnel instead of creating a new one.

Inputs: name (required), steps (required), siteId (required), reportId. Returns: id, name, steps

rybbit_create_goalCreate GoalB

Create a new conversion goal for a site. Goal can be path-based (URL match) or event-based (custom event triggered).

Inputs: config (required), siteId (required), goalType (required), name. Returns: id, name, message, success

rybbit_create_siteCreate SiteA

Create a new site in Rybbit. Use type 'web' for websites (domain like 'example.com') or type 'mobile' for mobile apps (package name like 'com.example.app'). 'app' is accepted as a legacy alias for 'mobile'. Returns the created site with its siteId for tracking integration.

Inputs: domain (required), organizationId (required), name, type. Returns: name, domain, siteId, message, +1 more

rybbit_delete_funnelDelete FunnelB
DestructiveIdempotent

Permanently delete a saved funnel. This action cannot be undone.

Inputs: siteId (required), funnelId (required). Returns: message, success

rybbit_delete_goalDelete GoalB
DestructiveIdempotent

Permanently delete a goal. This action cannot be undone.

Inputs: goalId (required), siteId (required). Returns: id, name, message, success

rybbit_delete_siteDelete SiteA
Destructive

Delete a site from Rybbit. This permanently removes the site and its replay data. Use rybbit_list_sites or rybbit_get_site_id to find site IDs.

Inputs: siteId (required). Returns: message, success

rybbit_describe_dimensionDescribe Filter DimensionA
Read-onlyIdempotent

Look up which tools accept a given filter dimension (e.g. 'event_name', 'pathname', 'country'), where it works natively, where it is silently stripped due to upstream bugs (with alternative tool suggestions), and example values. Use this before constructing a complex filters[] array.

Inputs: parameter (required). Returns: examples, parameter, valueHint, strippedIn, +3 more

rybbit_get_configGet Rybbit ConfigA
Read-onlyIdempotent

Get Rybbit server version and configuration

Inputs: no named parameters. Returns: version, mapboxToken, disableSignup

rybbit_get_errorsError TrackingA
Read-onlyIdempotent

Get error tracking data. Workflow: (1) type='names' to see error types and counts, (2) type='events' with errorMessage to see individual instances with stack traces, (3) type='timeseries' with errorMessage to see trends over time.

Inputs: siteId (required), page, type, limit, +8 more. Returns: data

rybbit_get_event_aggregateEvent AggregateA
Read-onlyIdempotent

Aggregate events by one or more dimensions (e.g. identified_user_id, traits.username, pathname, properties.room_id). Filters by event_name and optional property filters, then groups remaining events. Returns { groups: [{key, count, first_seen, last_seen, sessions, extras}], scanned, hitCount, hasMore }. When hasMore: true, the scan was capped — narrow the time window or raise maxScan for more accuracy.

Inputs: siteId (required), groupBy (required), topN, endDate, +8 more. Returns: groups, hasMore, scanned, hitCount, +2 more

rybbit_get_event_namesEvent NamesA
Read-onlyIdempotent

Get all custom event names and their occurrence counts for a site. Useful for discovering what events are being tracked.

Inputs: siteId (required), endDate, filters, timeZone, +3 more. Returns: data

rybbit_get_event_propertiesEvent PropertiesB
Read-onlyIdempotent

Get property breakdowns for a specific custom event. Returns the distinct property keys and values with counts.

Inputs: siteId (required), eventName (required), endDate, filters, +4 more. Returns: data

rybbit_get_event_timeseriesEvent Time SeriesB
Read-onlyIdempotent

Get custom event counts as time-series data with configurable buckets. Useful for analyzing event trends over time.

Inputs: siteId (required), bucket, endDate, filters, +4 more. Returns: data

rybbit_get_event_user_leaderboardEvent User LeaderboardA
Read-onlyIdempotent

Returns the top users for a given event (e.g. who sent the most pm_sent, who clicked the most ad_click). Groups by identified_user_id + traits.username. Answers questions like 'kdo dnes poslal nejvíc vzkazů'.

Inputs: siteId (required), eventName (required), topN, endDate, +7 more. Returns: groups, hasMore, scanned, hitCount, +2 more

rybbit_get_funnel_step_sessionsFunnel Step SessionsA
Read-onlyIdempotent

Get the sessions that reached (or dropped off at) a specific funnel step. Useful for drilling into why users drop off at a particular funnel step.

Inputs: mode (required), steps (required), siteId (required), stepNumber (required), +8 more. Returns: data

rybbit_get_goal_sessionsGoal SessionsA
Read-onlyIdempotent

Get sessions that completed a specific goal. Useful for analyzing which users and sessions triggered goal conversions.

Inputs: goalId (required), siteId (required), page, limit, +6 more. Returns: data

rybbit_get_journeysUser JourneysB
Read-onlyIdempotent

Get user journey (flow) analysis showing the most common navigation paths through the site. Shows sequences of pages users visit and how many sessions follow each path.

Inputs: siteId (required), steps, endDate, filters, +5 more. Returns: data

rybbit_get_metricMetric BreakdownA
Read-onlyIdempotent

Get metric breakdown by dimension. Use parameter='pathname' for top pages, 'browser'/'operating_system'/'device_type' for tech stats, 'country'/'city' for geo, 'utm_source'/'utm_campaign' for marketing, 'referrer'/'channel' for traffic sources, 'entry_page'/'exit_page' for user flow. Returns sorted list with counts, percentages, bounce rate, and session duration.

Inputs: siteId (required), parameter (required), page, limit, +6 more. Returns: data, totalCount

rybbit_get_overviewSite OverviewB
Read-onlyIdempotent

Get aggregated overview metrics for a site: sessions, pageviews, unique users, pages per session, bounce rate, and average session duration. Supports date range and filters.

Inputs: siteId (required), endDate, filters, timeZone, +3 more. Returns: users, sessions, pageviews, bounceRate, +2 more

rybbit_get_overview_timeseriesOverview Time SeriesB
Read-onlyIdempotent

Get overview metrics as time-series data with configurable time buckets (minute, hour, day, week, month). Returns arrays of data points for charting trends.

Inputs: siteId (required), bucket, endDate, filters, +4 more. Returns: data

rybbit_get_page_titlesGet Page TitlesA
Read-onlyIdempotent

Get the most-viewed page titles for a site, broken down by pageviews and unique sessions. Complements rybbit_get_metric with parameter='pathname' by giving the human-readable page title instead of just the path.

Inputs: siteId (required), endDate, filters, timeZone, +3 more. Returns: data

rybbit_get_performanceWeb VitalsA
Read-onlyIdempotent

Get Core Web Vitals performance metrics (LCP, CLS, INP, FCP, TTFB) with p50, p75, p90, p99 percentiles. Optionally break down by page path, browser, or OS.

Inputs: siteId (required), endDate, filters, timeZone, +4 more. Returns: data, cls_p50, cls_p75, cls_p90, +18 more

rybbit_get_performance_timeseriesWeb Vitals Time SeriesA
Read-onlyIdempotent

Get Core Web Vitals performance metrics as time-series data for trend analysis.

Inputs: siteId (required), bucket, endDate, filters, +4 more. Returns: data

rybbit_get_retentionUser RetentionB
Read-onlyIdempotent

Get user retention cohort analysis showing how many users return over time periods.

Inputs: siteId (required), endDate, filters, timeZone, +3 more. Returns: data, mode

rybbit_get_sessionSession DetailA
Read-onlyIdempotent

Get detailed session information including all page views, events, user traits, device info, location, and full event timeline. Use rybbit_list_sessions first to find session IDs.

Inputs: siteId (required), sessionId (required). Returns: os, city, device, events, +6 more

rybbit_get_session_locationsSession LocationsA
Read-onlyIdempotent

Get geographic session location data with coordinates. Returns latitude, longitude, city, country, and session count for map visualization and geographic analysis.

Inputs: siteId (required), page, limit, endDate, +5 more. Returns: data

rybbit_get_site_idGet Site ID by DomainA
Read-onlyIdempotent

Look up a site by domain name. Returns the numeric siteId used for analytics API queries. Note: for SDK tracking setup, use the hash siteId returned by rybbit_create_site instead.

Inputs: domain (required). Returns: matches, message

rybbit_get_userUser DetailB
Read-onlyIdempotent

Get detailed information about a specific user including their traits, session history, and activity summary.

Inputs: siteId (required), userId (required). Returns: data

rybbit_get_user_event_breakdownUser Event BreakdownA
Read-onlyIdempotent

Get event count breakdown for a specific user. Shows how many times each event_name was triggered by this user. Accepts either the Rybbit user_id (device hash) or the identified_user_id (app-provided user ID). Useful for analyzing per-user behavior like ad_click, chat_message_sent, etc.

Inputs: siteId (required), userId (required), endDate, filters, +4 more. Returns: data

rybbit_get_user_session_countUser Session CountA
Read-onlyIdempotent

Get the per-day session count for a single user across the requested time range. Useful for plotting user engagement intensity (calendar heatmap or sparkline).

Inputs: siteId (required), userId (required), endDate, timeZone, +3 more. Returns: data

rybbit_get_user_traitsUser TraitsA
Read-onlyIdempotent

Get user trait keys, values, or find users by trait. mode='keys' lists all trait keys. mode='values' (default when key is provided) returns distinct values for a trait key. mode='users' finds users matching a specific trait key+value pair (case-insensitive).

Inputs: siteId (required), key, mode, limit, +1 more. Returns: data, keys, values

rybbit_list_eventsList EventsA
Read-onlyIdempotent

List raw events for a site with filtering and pagination. Returns individual event records with timestamps, types, pathnames, event names, and properties. When filtering by event_name, only matching events are returned (not entire sessions). Use beforeTimestamp from a previous response's cursor.oldestTimestamp to paginate backwards through history.

Inputs: siteId (required), page, limit, endDate, +8 more. Returns: data, cursor

rybbit_list_funnelsList FunnelsA
Read-onlyIdempotent

List all saved funnels for a site with their step definitions.

Inputs: siteId (required). Returns: data

rybbit_list_goalsList GoalsB
Read-onlyIdempotent

List all goals for a site with their current conversion metrics and configuration.

Inputs: siteId (required), endDate, filters, timeZone, +3 more. Returns: data

rybbit_list_sessionsList SessionsA
Read-onlyIdempotent

List sessions for a site with filtering and pagination. Returns session ID, user info, device, location, pages visited, duration, bounce status, and IP address (if site has trackIp enabled). Supports client-side IP filtering.

Inputs: siteId (required), ip, page, limit, +8 more. Returns: data, filteredBy, scannedPages

rybbit_list_sitesList SitesA
Read-onlyIdempotent

List all sites and organizations the authenticated user has access to

Inputs: no named parameters. Returns: data

rybbit_list_usersList UsersA
Read-onlyIdempotent

List users for a site. Returns user IDs, session counts, first/last seen dates, and user traits. Supports filtering by most analytics dimensions. Use 'search' param to find users by username/email/name (case-insensitive partial match). IMPORTANT: event_name filter is silently STRIPPED here — upstream backend returns HTTP 500. To rank users by a specific event, use rybbit_get_event_user_leaderboard instead. Call rybbit_describe_dimension to see capability per filter dimension.

Inputs: siteId (required), page, limit, search, +10 more. Returns: data

rybbit_live_usersLive User CountA
Read-onlyIdempotent

Get the current number of live/active users on a site in real-time

Inputs: siteId (required). Returns: liveUsers

rybbit_site_has_dataSite Has DataA
Read-onlyIdempotent

Check whether a site has received any tracking events yet. Useful for verifying SDK integration before drilling into analytics.

Inputs: siteId (required). Returns: hasData

rybbit_update_goalUpdate GoalC
Idempotent

Update an existing goal's name, type, or configuration.

Inputs: config (required), goalId (required), siteId (required), goalType (required), +1 more. Returns: id, name, message, success

rybbit_update_site_configUpdate Site ConfigB
Idempotent

Update configuration for an existing Rybbit site. Change site identity (name, domain, type), toggle tracking features (IP, session replay, errors, button clicks, etc.), manage exclusions (IPs, countries, paths, hostnames, user agents), and public embedding.

Inputs: siteId (required), name, tags, type, +21 more. Returns: config, success

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 43 tools

    Disambiguation4/5

    Most tools target a clearly distinct resource and action, and descriptions explicitly clarify overlaps like rybbit_get_metric vs rybbit_get_page_titles or rybbit_get_event_aggregate vs rybbit_get_event_user_leaderboard. A few event- and user-oriented tools could still be confused at a glance, but the set is generally well separated.

    Naming Consistency4/5

    All tools use the rybbit_ prefix with snake_case naming, and most follow a clear verb_noun pattern such as rybbit_list_users, rybbit_get_event_properties, and rybbit_create_funnel. Minor deviations like rybbit_site_has_data and rybbit_live_users are descriptive but not strictly verb_noun.

    Tool Count2/5

    With 43 tools, the server is far above the 15-tool comfortable range for an MCP tool set. While the analytics domain is broad, many separate query endpoints could likely be consolidated or grouped, making this feel heavy for routine agent use.

    Completeness4/5

    The surface covers core analytics workflows well: site management, sessions, users, events, goals, funnels, performance, errors, and configuration. Some peripheral capabilities like annotations, dashboards, alerting, or user administration are absent, but the primary analytics lifecycle is substantially covered.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Connects Google Analytics 4 data to Claude, Cursor and other MCP clients, enabling natural language queries of website traffic, user behavior, and analytics data with access to 200+ GA4 dimensions and metrics.
      12
      2,370 PyPI
      244
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Connects MCP clients like Claude Desktop to Google Analytics 4 Data API, enabling natural language queries for reports, top pages, traffic sources, conversions, realtime users, and period comparisons.
      7
      70 PyPI
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Exposes Rybbit Analytics as MCP tools for querying site traffic, page views, visitor sessions, and live visitor counts through natural language.
      9
      78 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying Google Analytics 4 data using natural language through MCP clients like Claude and Cursor, supporting 200+ dimensions and metrics for traffic, user behavior, and e-commerce analysis.
      MIT