rybbit-mcp

@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 - page and limit parameters 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_sites for valid IDs

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

From source

For development or contributing:

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

Then 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

Both require RYBBIT_URL pointing to your Rybbit instance.

Tools (32)

Configuration and site management

Real-time and overview

Metrics and dimensions

Sessions

Users

Events

Errors

Performance (Web Vitals)

Funnels and goals

Journeys

Common parameters

All analytics tools support these optional parameters:

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

• Rybbit Analytics
• npm package
• @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 --noEmit

Contributing

Contributions are welcome! For major changes, please open an issue first.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: description')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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.