rybbit-mcp

Rybbit Analytics MCP Server

1. Purpose & Context

Rybbit is a privacy-first, open-source web analytics platform — a self-hosted alternative to Google Analytics. Data is stored in ClickHouse + PostgreSQL. Tracking is done via a JavaScript snippet, TypeScript SDK (@nks-hub/rybbit-ts), or Flutter SDK (rybbit_flutter_sdk).

This MCP server exposes 31 tools that let Claude query any Rybbit Analytics instance directly — no dashboard needed. Claude can retrieve traffic overviews, drill into sessions and users, analyze funnels and goals, investigate errors, audit Core Web Vitals performance, track custom events, and manage sites.

Package: @nks-hub/rybbit-mcp v0.5.2 Stack: TypeScript, @modelcontextprotocol/sdk v1.27+, Zod, Node.js 18+ Transport: StdioServerTransport (local, for Claude Code)

2. Configuration

Environment Variables

Variable	Required	Description
RYBBIT_URL	Yes	Base URL of the Rybbit instance (e.g., https://analytics.example.com)
RYBBIT_API_KEY	Recommended	API key for Bearer token authentication
RYBBIT_EMAIL	Alternative	Email for email/password auth (uses better-auth session cookies)
RYBBIT_PASSWORD	Alternative	Password for email/password auth

Claude Code MCP Config

Add to ~/.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"
      }
    }
  }
}

Or from a local clone:

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

3. Workflow: Getting Started

1. Always start with rybbit_list_sites to discover available sites and their IDs.
2. Use rybbit_get_overview with a site ID for a quick traffic summary.
3. Drill into specific areas as needed: metrics, sessions, users, events, errors, performance.