<picture>
   <source media="(prefers-color-scheme: dark)" srcset="art/header-dark.png">
   <img alt="Logo for Rybbit MCP Server" src="art/header-light.png">
</picture>

# Rybbit MCP Server

> [!NOTE]
> Rybbit now ships an [official MCP server](https://rybbit.com/docs/mcp) — 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](#how-this-compares-to-the-official-rybbit-mcp).

An MCP (Model Context Protocol) server for the [Rybbit Analytics](https://rybbit.com) 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:

```bash
npm install -g rybbit-mcp-server
```

## Configuration

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `RYBBIT_API_KEY` | Yes | — | Your Rybbit API key |
| `RYBBIT_URL` | No | `https://app.rybbit.io` | Base URL for the Rybbit API (for self-hosted instances) |
| `RYBBIT_CACHE_TTL` | No | `60` | Seconds to cache GET responses in memory (`0` disables; live visitor counts are never cached) |
| `RYBBIT_READ_ONLY` | No | off | Set to `1` or `true` to run read-only: all 18 write tools (goal/funnel/site/team create-update-delete, member management, user identify/traits/delete, event tracking) are hidden from the tool list and rejected if called |

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

| Capability | Official MCP | This package |
|---|:---:|:---:|
| Analytics reads (overview, timeseries, breakdowns, live, retention, journeys, web vitals, errors) | ✅ | ✅ |
| Sessions, events, users (raw data reads) | ✅ | ✅ |
| Goals & funnels (read, analyze, CRUD) | ✅ | ✅ |
| Sites & organizations (CRUD, members) | ✅ | ✅ |
| Raw read-only ClickHouse SQL (`run_query` + schema) | ✅ | ✅ |
| User identify / traits / GDPR delete | ✅ | ✅ |
| Teams & member site-access management | ✅ | ✅ |
| Extra read tools (goal sessions, funnel step sessions, performance timeseries & by-dimension, error events & timeseries, session locations, user session counts, event properties, outbound links) | ❌ | ✅ |
| Event ingestion (`rybbit_track_event`) | ❌ | ✅ |
| Batch event ingestion (`rybbit_track_events`, 1–50 per call) | ❌ | ✅ |
| Composite digest (`rybbit_get_site_summary`) | ❌ | ✅ |
| Period-over-period comparison (`rybbit_compare_periods`) | ❌ | ✅ |
| Response caching + rate-limit awareness | ❌ | ✅ |
| Read-only mode via env flag | ❌ | ✅ |
| Local stdio transport (no remote MCP/OAuth support needed) | ❌ | ✅ |
| Hosted remote endpoint (nothing to run locally) | ✅ | ❌ |
| OAuth authorization flow | ✅ | ❌ |

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

```json
{
  "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:

```json
{
  "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`):

```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

```bash
npx rybbit-mcp-server

# Or if installed globally:
rybbit-mcp-server
```

## Example Questions

| You ask... | Tools used |
|---|---|
| "How many people visited last week, and what pages did they view?" | `rybbit_get_site_summary` |
| "Show the daily traffic trend this month" | `rybbit_get_overview_timeseries` |
| "Where is my traffic coming from?" | `rybbit_get_metric` (referrer, country, utm_source) |
| "Who are my most active users, and what did they do?" | `rybbit_get_users` → `rybbit_get_user_sessions` |
| "Trace one visitor's journey" | `rybbit_get_user_sessions` → `rybbit_get_session_details` |
| "How many people are on the site right now?" | `rybbit_get_live_visitors` |
| "Is the site healthy?" | `rybbit_get_performance_overview` + `rybbit_get_error_names` |
| "How is my signup funnel converting?" | `rybbit_get_funnels` → `rybbit_analyze_funnel` |
| "What are the most common paths through my site?" | `rybbit_get_journeys` |
| "Are users coming back?" | `rybbit_get_retention` |

## 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:
```json
[
  {
    "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