README.md
@nks-hub/rybbit-mcp
MCP server for Rybbit Analytics — query statistics, errors, users, sessions, funnels, goals, and performance metrics directly from Claude Code or any MCP-compatible client.
Why?
Instead of manually checking the Rybbit dashboard, let your AI assistant query analytics data directly:
- "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"
Quick Start
Installation
npm install -g @nks-hub/rybbit-mcp
Or clone and build:
git clone https://github.com/nks-hub/rybbit-mcp.git
cd rybbit-mcp
npm install && npm run build
Configuration
Add to your ~/.claude/settings.json or project .claude/settings.json:
{
"mcpServers": {
"rybbit": {
"command": "npx",
"args": ["-y", "@nks-hub/rybbit-mcp"],
"env": {
"RYBBIT_URL": "https://your-rybbit-instance.com",
"RYBBIT_API_KEY": "your-api-key"
}
}
}
}
Usage
Ask Claude Code anything about your analytics data. The MCP tools are automatically available.
Features
| Feature | Description |
|---|---|
| 31 Analytics Tools | Complete coverage of Rybbit API — overview, metrics, sessions, users, events, errors, performance, funnels, goals, journeys, site management |
| Flexible Auth | API key (recommended) or email/password authentication |
| Smart 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 | Configurable bucket granularity from minutes to years |
| Pagination | Built-in page/limit support for large datasets |
| Response Truncation | Auto-truncation at 25k chars to prevent context bloat |
| Actionable Errors | Error messages guide the LLM toward correct tool usage |
Authentication
Supports two authentication methods:
| 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 (31)
Configuration & 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 in an organization |
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 & 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 & 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 and pagination |
rybbit_get_session |
Full session detail with events and user traits |
Users
| Tool | Description |
|---|---|
rybbit_list_users |
Identified users with session counts and traits |
rybbit_get_user |
User detail with traits and activity |
rybbit_get_user_traits |
Trait keys, values, or find users by trait |
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 |
Tools 8
rybbit_get_configGet server version and configurationrybbit_list_sitesList all sites and organizationsrybbit_live_usersCurrent active users countrybbit_get_overviewAggregated metrics including sessions, pageviews, users, bounce rate, and durationrybbit_get_metricBreakdown by dimension such as browser, OS, country, page, or UTMrybbit_list_sessionsSession list with filtering and paginationrybbit_list_usersIdentified users with session counts and traitsrybbit_list_eventsRaw event records with filteringEnvironment Variables
RYBBIT_URLrequiredThe URL of your Rybbit instanceRYBBIT_API_KEYAPI key for authenticationRYBBIT_EMAILEmail for authenticationRYBBIT_PASSWORDPassword for authenticationTry it
→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.