rybbit-mcp

An MCP server that exposes Rybbit Analytics as tools for Claude (or any MCP-compatible client). Ask Claude things like:

• "What's the traffic overview for my site this week?"
• "What are the top 10 pages by visits this month?"
• "How many people are on the site right now?"
• "Where is my traffic coming from, by country?"
• "Show me the most recent sessions from mobile users."

It works against both Rybbit Cloud (app.rybbit.io) and self-hosted Rybbit instances.

Tools

Tool	Description
rybbit_list_sites	List organizations and sites (with their site IDs)
rybbit_get_site	Get config/details for one site
rybbit_get_overview	Sessions, pageviews, users, bounce rate, duration for a time range
rybbit_get_overview_timeseries	Same metrics bucketed over time (for trend charts)
rybbit_get_breakdown	Top pages, referrers, countries, browsers, devices, UTM params, etc.
rybbit_get_live_visitors	Current active visitor count
rybbit_list_sessions	Paginated list of visitor sessions
rybbit_get_session	Full detail + event list for one session
rybbit_get_session_locations	Aggregated session geolocation, for mapping

This covers Rybbit's Overview and Sessions API families. The same client/tool pattern can be extended to Events, Users, Goals, Funnels, Performance, and Errors — see Extending below.

Setup

1. Get a Rybbit API key

In your Rybbit dashboard: Settings → Account → API Keys → Create.

Self-hosted instances have no rate limits. Rybbit Cloud rate-limits API keys per your plan (Standard: 20 req/min, Pro: 200 req/min); Free/Basic plans don't get API key access.

2. Build the server

git clone https://github.com/<your-username>/rybbit-mcp.git
cd rybbit-mcp
npm install
npm run build

This produces build/index.js.

3. Configure your MCP client

Claude Desktop / Claude Code — add to your MCP config (claude_desktop_config.json or .claude/settings.json):

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

If you self-host Rybbit, set RYBBIT_URL to your instance's base URL instead (e.g. https://analytics.yourdomain.com).

Restart Claude Desktop / reload Claude Code, and the rybbit_* tools should appear.

Deploying to CapRover (or Docker)

This MCP server supports Server-Sent Events (SSE) for remote clients over HTTP. This is perfect for deploying to a platform like CapRover so that a remote AI agent can access the tools.

1. Create a new App in your CapRover dashboard (e.g., rybbit-mcp).
2. Set the Environment Variables in CapRover:
   • RYBBIT_URL
   • RYBBIT_API_KEY
   • PORT=3000 (Optional, defaults to 3000)
3. Under the Deployment tab, deploy using the Captain Definition or simply push this repository via the CapRover CLI. This repository contains a Dockerfile that CapRover will automatically detect and build.

Once deployed, the SSE endpoint will be available at: https://rybbit-mcp.your-caprover-domain.com/sse

Your remote AI agents can connect to this URL via SSEServerTransport instead of stdio.

4. Try it

"Use rybbit to show me an overview of site 123 for the last 7 days" "What are the top pages on my site this month?" "How many live visitors do I have right now?"

Development

npm run watch       # recompile on change
npm run inspector    # open the MCP Inspector against this server

Extending

Rybbit's API has more endpoint families than this v1 covers (Events, Users, Goals, Funnels, Performance metrics, Errors — see the Rybbit API docs). To add one:

1. Add a method to src/rybbit-client.ts calling the endpoint.
2. Register a corresponding tool in src/index.ts with server.registerTool(...), using zod for the input schema.
3. npm run build and reload your MCP client.

License

MIT