rybbit-mcp
The rybbit-mcp server provides 32 tools to query and manage a Rybbit Analytics instance directly from MCP-compatible AI clients, covering real-time visitors, site management, user behavior, events, errors, performance, funnels, goals, and journeys.
Site Management: List/create/delete/update sites, look up site IDs by domain, update tracking config (IP tracking, session replay, error tracking, bot blocking, excluded IPs/countries, etc.), and verify SDK integration.
Real-Time & Overview: Get live active user counts, aggregated metrics (sessions, pageviews, unique users, bounce rate, session duration), time-series trends with configurable bucket granularity, and geographic session data for map visualization.
Metrics & Dimensions: Break down metrics by browser, OS, country, city, page, UTM parameters, referrer, device type, channel, entry/exit pages, app version, and more. Also supports page title analysis and user retention cohorts.
Sessions: List sessions with filters (IP, identified users, min duration, dimension), get full session details including page views, events, user traits, device info, and event timeline.
Users: List users with search/sort/filters, view detailed profiles (traits, session history, activity summary), query user trait keys/values, find users by trait, get per-user event breakdowns, and per-day session counts.
Events: List raw events, discover custom event names and counts, get property breakdowns for specific events, view event count trends as time series, and track outbound link clicks.
Error Tracking: Get error type summaries, individual error instances with stack traces, and error trends over time.
Performance (Web Vitals): Get Core Web Vitals (LCP, CLS, INP, FCP, TTFB) with p50/p75/p90/p99 percentiles, broken down by page, browser, or OS, with time-series trend support.
Funnels: List saved funnels, analyze ad-hoc funnels with custom steps (conversion rates & drop-off), get sessions that reached or dropped off at specific steps, and create/delete funnels.
Goals: List, create, update, and delete goals (path-based or event-based with property filters); get sessions that completed a specific goal.
User Journeys: Analyze common page navigation sequences across sessions with configurable step depth (2–10 steps).
Filtering & Time Ranges: Filter by 22+ dimensions with 8 comparison types. Use absolute dates (YYYY-MM-DD) or relative time (pastMinutesStart), with IANA timezone support. Built-in pagination for large datasets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@rybbit-mcp Show me the top pages by bounce rate this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@nks-hub/rybbit-mcp
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 -
pageandlimitparameters 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_sitesfor valid IDs
Related MCP server: GA4 MCP Server
Requirements
Node.js: 18+
Rybbit Analytics: Self-hosted or cloud instance
Installation
npx (recommended)
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-mcpFrom source
For development or contributing:
git clone https://github.com/nks-hub/rybbit-mcp.git
cd rybbit-mcp
npm install && npm run buildThen 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 |
| Recommended for production |
Email/password |
| Development/testing |
Both require RYBBIT_URL pointing to your Rybbit instance.
Tools (32)
Configuration and site management
Tool | Description |
| Get server version and configuration |
| List all sites and organizations |
| Create a new site (type: |
| Delete a site permanently |
| Look up site ID by domain name |
| Update site tracking config (IP, errors, replay, etc.) |
Real-time and overview
Tool | Description |
| Current active users count |
| Aggregated metrics (sessions, pageviews, users, bounce rate, duration) |
| Metrics as time-series with configurable buckets |
| Geographic session data with coordinates for map visualization |
Metrics and dimensions
Tool | Description |
| Breakdown by dimension (browser, OS, country, page, UTM, etc.) |
| User retention cohort analysis |
Sessions
Tool | Description |
| Session list with filtering by IP, identified users, min duration, and pagination |
| Full session detail with events and user traits |
Users
Tool | Description |
| Users with search, sort (first/last seen, pageviews, sessions, duration), and identified-only filter |
| User detail with traits and activity |
| Trait keys, values, or find users by trait |
| Per-user event count breakdown |
Events
Tool | Description |
| Raw event records with filtering |
| Custom event names and counts |
| Property breakdowns per event |
| Event count trends over time with configurable buckets |
| Outbound link clicks with URLs and counts |
Errors
Tool | Description |
| Error types/counts, individual instances, or timeseries for a specific error |
Performance (Web Vitals)
Tool | Description |
| Core Web Vitals (LCP, CLS, INP, FCP, TTFB) with percentiles |
| Web Vitals trends over time |
Funnels and goals
Tool | Description |
| Saved funnels with step definitions |
| Ad-hoc funnel analysis with custom steps |
| Sessions that reached or dropped off at a funnel step |
| Goals with conversion metrics |
| Sessions that completed a specific goal |
Journeys
Tool | Description |
| User navigation path analysis |
Common parameters
All analytics tools support these optional parameters:
Parameter | Type | Description |
| string | Site identifier (required) |
| string | Start date |
| string | End date |
| string | IANA timezone (e.g., |
| array | Filter array |
| 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
Related projects
@nks-hub/rybbit-ts: TypeScript tracking SDK
rybbit-flutter-sdk: Flutter/Dart tracking SDK
Development
# Install dependencies
npm install
# Build
npm run build
# Watch mode
npm run dev
# Type checking
npx tsc --noEmitContributing
Contributions are welcome! For major changes, please open an issue first.
Fork the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Commit your changes (
git commit -m 'feat: description')Push to the branch (
git push origin feature/amazing-feature)Open a Pull Request
Support
📧 Email: dev@nks-hub.cz
🐛 Bug reports: GitHub Issues
📖 MCP Protocol: modelcontextprotocol.io
License
MIT License — see LICENSE for details.
Available Tools
43 toolsrybbit_analyze_funnelAnalyze FunnelBRead-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 FunnelBDestructiveIdempotent
Permanently delete a saved funnel. This action cannot be undone.
Inputs: siteId (required), funnelId (required). Returns: message, success
rybbit_delete_goalDelete GoalBDestructiveIdempotent
Permanently delete a goal. This action cannot be undone.
Inputs: goalId (required), siteId (required). Returns: id, name, message, success
rybbit_delete_siteDelete SiteADestructive
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 DimensionARead-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 ConfigARead-onlyIdempotent
Get Rybbit server version and configuration
Inputs: no named parameters. Returns: version, mapboxToken, disableSignup
rybbit_get_errorsError TrackingARead-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 AggregateARead-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 NamesARead-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 PropertiesBRead-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 SeriesBRead-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 LeaderboardARead-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 SessionsARead-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 SessionsARead-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 JourneysBRead-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 BreakdownARead-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_outbound_linksOutbound LinksBRead-onlyIdempotent
Get outbound link clicks tracked on the site. Shows which external URLs users are clicking and how often.
Inputs: siteId (required), page, limit, endDate, +5 more. Returns: data
rybbit_get_overviewSite OverviewBRead-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 SeriesBRead-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 TitlesARead-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 VitalsARead-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 SeriesARead-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 RetentionBRead-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 DetailARead-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 LocationsARead-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 DomainARead-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 DetailBRead-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 BreakdownARead-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 CountARead-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 TraitsARead-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 EventsARead-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 FunnelsARead-onlyIdempotent
List all saved funnels for a site with their step definitions.
Inputs: siteId (required). Returns: data
rybbit_list_goalsList GoalsBRead-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 SessionsARead-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 SitesARead-onlyIdempotent
List all sites and organizations the authenticated user has access to
Inputs: no named parameters. Returns: data
rybbit_list_usersList UsersARead-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 CountARead-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 DataARead-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 GoalCIdempotent
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 ConfigBIdempotent
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
Scored across 43 tools
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.
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.
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.
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
Related MCP Connectors
Read-only analytics for Convex apps, queryable via MCP from Claude, Cursor, and other clients.
Query your Betterlytics web analytics from AI agents: traffic, funnels, journeys, errors, uptime.
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
Ask your website analytics in plain language and set up funnels, features and dashboards.
Related MCP Servers
- AlicenseAqualityBmaintenanceConnects 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.122,370 PyPI244MIT
- AlicenseAqualityCmaintenanceConnects 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.770 PyPIMIT
- AlicenseAqualityDmaintenanceExposes Rybbit Analytics as MCP tools for querying site traffic, page views, visitor sessions, and live visitor counts through natural language.978 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables 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