MCP (Model Context Protocol)

The MCP endpoint exposes Databuddy analytics as tools over the Model Context Protocol. Use it from Cursor, Claude Code, or any MCP client to query analytics via natural language or structured tool calls.

Setup

CursorClaude Code

After install, go to Cursor Settings → Features → MCP → Databuddy and replace YOUR_API_KEY with your key from API Keys.

Endpoint: https://api.databuddy.cc/v1/mcp/ · Auth: x-api-key or Authorization: Bearer with read:data scope

Tools

ask

Natural language analytics. Parameters: question (required), conversationId (optional, for follow-ups).

list_websites

No parameters. Returns websites (id, name, domain, isPublic) and total.

get_data

Single: websiteId, type, plus preset or from+to. Optional: limit, filters, groupBy, orderBy, timezone.

Batch: websiteId, queries (2–10 items). Each item: type + preset or from+to.

Filters: field, op (eq|ne|contains|not_contains|starts_with|in|not_in), value.

Date presets: today, yesterday, last_7d, last_14d, last_30d, last_90d, this_week, last_week, this_month, last_month, this_year

{
"websiteId": "web_abc123",
"type": "pages",
"preset": "last_30d",
"limit": 10
}

get_schema

No parameters. Returns full ClickHouse schema docs.

capabilities

No parameters. Returns query types, schema summary, date presets, max limit (1000), and hints.

Query types

Same as Analytics Queries: summary, pages, traffic, browser_name, os_name, device_types, countries, cities, errors, performance, sessions, custom_events, profiles, outbound_links, outbound_domains, engagement. Link types (link_total_clicks, etc.) when using link_id.

Errors

On failure, response includes error and isError: true. Common causes: missing read:data scope, invalid websiteId, missing type or date range, malformed batch.

Tips

1. Call list_websites first.
2. Use capabilities to discover types and presets.
3. Use ask + conversationId for conversational flows.
4. Batch get_data (2–10 queries) to reduce round-trips.