rybbit-super-mcp

Extended MCP server for Rybbit Analytics — 48 tools with full CRUD for funnels, goals, and sites. Query statistics, manage funnels, create goals, and analyze performance directly from Claude Code.

Why?

Instead of switching to the Rybbit dashboard, let the LLM query and manage your analytics directly:

• "Create a checkout funnel: homepage → product → cart → order confirmation"
• "What's the drop-off rate on the signup funnel?"
• "Set up conversion goals for purchases and newsletter signups"
• "Delete all test funnels"
• "Show me top pages by bounce rate for the last 7 days"
• "Which countries drive the most traffic?"

Quick Start

Installation

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

Configuration

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

Option 1 — Local path (recommended):

{
  "mcpServers": {
    "rybbit": {
      "command": "node",
      "args": ["/absolute/path/to/rybbit-super-mcp/build/index.js"],
      "env": {
        "RYBBIT_URL": "https://your-rybbit-instance.com",
        "RYBBIT_API_KEY": "your-api-key-here",
        "RYBBIT_EMAIL": "your-email@example.com",
        "RYBBIT_PASSWORD": "your-password"
      }
    }
  }
}

API key is used first for all read operations (stateless, fast). For CRUD operations (funnels/goals), the MCP automatically falls back to session auth if the API key returns 403. See Authentication for details.

Option 2 — Via npx (no clone needed):

{
  "mcpServers": {
    "rybbit": {
      "command": "npx",
      "args": ["-y", "github:Tchoow/rybbit-super-mcp"],
      "env": {
        "RYBBIT_URL": "https://your-rybbit-instance.com",
        "RYBBIT_API_KEY": "your-api-key-here",
        "RYBBIT_EMAIL": "your-email@example.com",
        "RYBBIT_PASSWORD": "your-password"
      }
    }
  }
}

Features

Category	Tools	Description
Configuration & Sites	8	Server config, list/create/update/delete sites, site details, excluded IPs/countries
Real-time & Overview	4	Live users, overview metrics, time series, session locations
Metrics & Dimensions	3	Metric breakdown by 22 dimensions, retention, page titles
Sessions	2	List sessions with IP filtering, session detail with event timeline
Users	5	List users, user detail, user traits, event breakdown, session count timeline
Events	6	List events, event names, properties, time series, outbound links, event count by type
Errors	1	Error tracking (names, events, timeseries modes)
Performance	2	Core Web Vitals (LCP, CLS, INP, FCP, TTFB) with time series
Funnels	7	List, analyze, step sessions + create, update, delete, batch create
Goals	6	List, goal sessions + create, update, delete, batch create
Journeys	1	User journey/flow analysis
Organization	2	Org event count, check site has data

Tools (48)

Configuration & Site Management (8)

Tool	Description
rybbit_get_config	Get Rybbit server version and configuration
rybbit_list_sites	List all sites and organizations
rybbit_get_site_id	Look up a site ID by domain name
rybbit_get_site_details	NEW — Get full site config (tracking flags, domain, etc.)
rybbit_create_site	Create a new site in an organization
rybbit_update_site_config	Update site tracking settings (IP, errors, replay, etc.)
rybbit_delete_site	Delete a site permanently
rybbit_get_excluded_ips	NEW — List IPs excluded from tracking
rybbit_get_excluded_countries	NEW — List countries excluded from tracking

Real-time & Overview (4)

Tool	Description
rybbit_live_users	Current live/active user count
rybbit_get_overview	Aggregated metrics: sessions, pageviews, users, bounce rate
rybbit_get_overview_timeseries	Overview metrics as time-series with configurable buckets
rybbit_get_session_locations	Geographic session data with coordinates

Metrics & Dimensions (3)

Tool	Description
rybbit_get_metric	Breakdown by dimension (browser, country, pathname, UTM, etc.)
rybbit_get_retention	User retention cohort analysis
rybbit_get_page_titles	NEW — Page titles with visit counts and avg time on page

Sessions (2)

Tool	Description
rybbit_list_sessions	List sessions with filtering, pagination, IP search
rybbit_get_session	Session detail with full event timeline

Users (5)

Tool	Description
rybbit_list_users	List users with search, sorting, identified-only filter
rybbit_get_user	User detail with traits and activity
rybbit_get_user_traits	User trait keys, values, or find users by trait
rybbit_get_user_event_breakdown	Per-user event count breakdown
rybbit_get_user_session_count	NEW — Daily session count timeline for a specific user

Events (6)

Tool	Description
rybbit_list_events	Raw event records with filtering
rybbit_get_event_names	All custom event names with counts
rybbit_get_event_properties	Property breakdown for a specific event
rybbit_get_event_timeseries	Event counts as time-series
rybbit_get_outbound_links	Outbound link click tracking
rybbit_get_site_event_count	NEW — Event counts by type (pageviews, custom, errors, etc.)

Errors (1)

Tool	Description
rybbit_get_errors	Error tracking: names, individual events, or timeseries

Performance (2)

Tool	Description
rybbit_get_performance	Core Web Vitals with percentiles, optional dimension breakdown
rybbit_get_performance_timeseries	Web Vitals trends over time

Funnels (3 read + 4 CRUD)

Tool	Description
rybbit_list_funnels	List all saved funnels
rybbit_analyze_funnel	Ad-hoc funnel analysis (without saving)
rybbit_get_funnel_step_sessions	Sessions that reached/dropped at a funnel step
rybbit_create_funnel	NEW — Create and save a funnel
rybbit_update_funnel	NEW — Update a funnel's name or steps
rybbit_delete_funnel	NEW — Delete a saved funnel
rybbit_batch_create_funnels	NEW — Create multiple funnels at once

Goals (2 read + 4 CRUD)

Tool	Description
rybbit_list_goals	List goals with conversion metrics
rybbit_get_goal_sessions	Sessions that completed a goal
rybbit_create_goal	NEW — Create a conversion goal
rybbit_update_goal	NEW — Update a goal
rybbit_delete_goal	NEW — Delete a goal
rybbit_batch_create_goals	NEW — Create multiple goals at once

Journeys (1)

Tool	Description
rybbit_get_journeys	User journey/flow analysis with common navigation paths

Organization & Utilities (2)

Tool	Description
rybbit_get_org_event_count	NEW — Aggregated event counts across all sites in an org
rybbit_check_site_has_data	NEW — Check if a site has any recorded events (boolean)

Common Parameters

Date Ranges

Most analytics tools accept either absolute or relative date ranges:

• Absolute: startDate / endDate in YYYY-MM-DD format
• Relative: pastMinutesStart / pastMinutesEnd (e.g., pastMinutesStart: 60 = last hour)

Filters

[
  { "parameter": "country", "type": "equals", "value": ["US", "FR"] },
  { "parameter": "browser", "type": "not_equals", "value": ["IE"] },
  { "parameter": "pathname", "type": "contains", "value": ["/blog"] }
]

Available filter dimensions: 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

For time-series endpoints: minute, five_minutes, ten_minutes, fifteen_minutes, hour, day, week, month, year.

Pagination

• page: Page number (1-indexed)
• limit: Results per page (max 200)

Authentication

Two modes are supported. API key + email/password is the recommended setup for full access:

Mode	Environment Variables	CRUD Support
API Key + Email/Password (recommended)	RYBBIT_API_KEY, RYBBIT_EMAIL, RYBBIT_PASSWORD	All 48 tools (automatic fallback)
API Key only	RYBBIT_API_KEY	Read + site config (CRUD may fail on older Rybbit versions)
Email/Password only	RYBBIT_EMAIL, RYBBIT_PASSWORD	All 48 tools

All modes require RYBBIT_URL — the URL of your Rybbit instance (without trailing slash).

How it works: API key is used first (stateless, fast). If a CRUD request returns 403 and email/password credentials are available, the MCP automatically retries with session auth. This transparent fallback ensures all 48 tools work regardless of the Rybbit server version.

Recommended config (full access):

{
  "mcpServers": {
    "rybbit": {
      "command": "node",
      "args": ["/path/to/rybbit-super-mcp/build/index.js"],
      "env": {
        "RYBBIT_URL": "https://your-rybbit-instance.com",
        "RYBBIT_API_KEY": "your-api-key-here",
        "RYBBIT_EMAIL": "your-email@example.com",
        "RYBBIT_PASSWORD": "your-password"
      }
    }
  }
}

E-commerce Examples

PrestaShop Checkout Funnel

"Create a checkout funnel for my PrestaShop store with these steps:
1. Homepage (/)
2. Product Page (/en/*/*.html)
3. Add to Cart (event: add_to_cart)
4. Checkout (/en/order)
5. Purchase Confirmation (/en/order-confirmation)"

Conversion Goals (Batch)

Goals use goalType ("path" or "event") and a config object:

"Create these conversion goals for my e-commerce site:
- Purchase: goalType=path, config.pathPattern=/order-confirmation
- Add to Cart: goalType=event, config.eventName=add_to_cart
- Newsletter: goalType=event, config.eventName=newsletter_subscribe
- Contact Form: goalType=path, config.pathPattern=/contact-success
- Account Created: goalType=event, config.eventName=user_registered"

Funnel Drop-off Analysis

"Analyze the checkout funnel and show me which step has the highest drop-off.
Then get the sessions that dropped off at that step so I can understand why."

Differences from upstream

Feature	@nks-hub/rybbit-mcp	rybbit-super-mcp
Total tools	32	48
Create funnel	—	rybbit_create_funnel
Update funnel	—	rybbit_update_funnel
Delete funnel	—	rybbit_delete_funnel
Batch create funnels	—	rybbit_batch_create_funnels
Create goal	—	rybbit_create_goal
Update goal	—	rybbit_update_goal
Delete goal	—	rybbit_delete_goal
Batch create goals	—	rybbit_batch_create_goals
Page titles	—	rybbit_get_page_titles
Site event count	—	rybbit_get_site_event_count
Org event count	—	rybbit_get_org_event_count
Site has data	—	rybbit_check_site_has_data
User session count	—	rybbit_get_user_session_count
Site details	—	rybbit_get_site_details
Excluded IPs	—	rybbit_get_excluded_ips
Excluded countries	—	rybbit_get_excluded_countries
Auth priority	API key first	API key first + automatic session fallback on 403
LLM instructions	Basic workflow	Full CRUD workflow guide

Development

npm install        # Install dependencies
npm run build      # Compile TypeScript
npm run dev        # Watch mode (recompile on change)
npm start          # Run the compiled server

Credits

Fork of @nks-hub/rybbit-mcp by NKS Hub. Extended by Tchoow / Flowcode.

License

MIT