MCP Server

@kitbase/analytics-mcp is an MCP (Model Context Protocol) server that lets AI assistants query your Kitbase analytics data. Connect it to Claude Code, Cursor, or any MCP-compatible client and ask questions about your traffic, events, users, sessions, funnels, journeys, and frustration signals in natural language.

No Dashboard Required

Once connected, your AI assistant can answer questions like "How many visitors did we get last week?" or "Show me the signup funnel conversion rate" by querying the Kitbase API directly.

Installation

npmpnpmyarn

bash

npm install @kitbase/analytics-mcp

bash

pnpm add @kitbase/analytics-mcp

bash

yarn add @kitbase/analytics-mcp

Or run directly without installing:

bash

npx @kitbase/analytics-mcp

Configuration

The server is configured entirely through environment variables:

Variable	Required	Description
`KITBASE_API_KEY`	Yes	Private API key (must start with `sk_kitbase_`)
`KITBASE_API_URL`	No	Kitbase API base URL (default: `https://api.kitbase.dev`)

The project and environment are automatically resolved from the API key — no need to specify them manually.

WARNING

The MCP server requires a private API key (sk_kitbase_), not the public SDK token used in browser SDKs. Generate one from your Kitbase dashboard under Settings > API Keys.

Client Setup

Claude Code

Add to your Claude Code MCP configuration (.claude/settings.json or project-level .mcp.json):

json

{
  "mcpServers": {
    "kitbase-analytics": {
      "command": "npx",
      "args": ["@kitbase/analytics-mcp"],
      "env": {
        "KITBASE_API_KEY": "sk_kitbase_your_key_here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json):

json

{
  "mcpServers": {
    "kitbase-analytics": {
      "command": "npx",
      "args": ["@kitbase/analytics-mcp"],
      "env": {
        "KITBASE_API_KEY": "sk_kitbase_your_key_here"
      }
    }
  }
}

Other MCP Clients

The server communicates over stdio using the standard MCP protocol. Use the same configuration format — any MCP-compatible client will work.

Available Tools

The server exposes 15 tools across seven categories.

Web Analytics

Tool	Description
`get_web_summary`	Summary KPIs (visitors, pageviews, bounce rate, etc.) with percentage changes vs previous period
`get_web_timeline`	Metrics over time — timeseries data for charting trends
`get_web_breakdown`	Break down metrics by dimension (pages, countries, browsers, referrers, UTM params, etc.)
`compare_periods`	Compare analytics between two time periods — shows which dimension values changed the most

`get_web_summary`

Returns aggregate KPIs for the given date range along with percentage changes compared to the previous period.

Parameter	Type	Required	Description
`preset`	`string`	No	Date preset — see Date Filtering
`from`	`string`	No	Start date (`YYYY-MM-DD`)
`to`	`string`	No	End date (`YYYY-MM-DD`)
`timezone`	`string`	No	Timezone (default: `UTC`)
`filters`	`string[]`	No	Filters — see Filters

`get_web_timeline`

Returns timeseries data for a single metric, useful for charting trends over time.

Parameter	Type	Required	Description
`metric`	`string`	Yes	Metric to chart (`visitors`, `pageviews`, `bounce_rate`, `visit_duration`, `views_per_visit`)
`preset`	`string`	No	Date preset
`from` / `to`	`string`	No	Explicit date range (`YYYY-MM-DD`)
`timezone`	`string`	No	Timezone (default: `UTC`)
`filters`	`string[]`	No	Filters

`get_web_breakdown`

Breaks down a metric by a given dimension — for example, top pages by visitors, or traffic by country.

Parameter	Type	Required	Description
`dimension`	`string`	Yes	Dimension to break down by (`page`, `country`, `browser`, `os`, `device`, `referrer`, `utm_source`, `utm_medium`, `utm_campaign`)
`metric`	`string`	No	Metric to sort by (default: `visitors`)
`preset`	`string`	No	Date preset
`from` / `to`	`string`	No	Explicit date range (`YYYY-MM-DD`)
`timezone`	`string`	No	Timezone (default: `UTC`)
`filters`	`string[]`	No	Filters
`page`	`number`	No	Page number (0-indexed)
`size`	`number`	No	Page size

`compare_periods`

Compares web analytics for a dimension across two date ranges, highlighting which values changed the most between the periods.

Parameter	Type	Required	Description
`dimension`	`string`	Yes	Dimension to compare (`page`, `country`, `browser`, `os`, `device`, `referrer`, `utm_source`, `utm_medium`, `utm_campaign`)
`currentFrom`	`string`	Yes	Current period start date (`YYYY-MM-DD`)
`currentTo`	`string`	Yes	Current period end date (`YYYY-MM-DD`)
`previousFrom`	`string`	Yes	Previous period start date (`YYYY-MM-DD`)
`previousTo`	`string`	Yes	Previous period end date (`YYYY-MM-DD`)
`timezone`	`string`	No	Timezone (default: `UTC`)
`limit`	`number`	No	Max number of results (default: `10`)
`filters`	`string[]`	No	Filters — see Filters

Events

Tool	Description
`list_events`	List tracked events with filtering by name, user, or date range
`get_event_stats`	Aggregated event statistics with timeline and optional property breakdown

`list_events`

Lists individual tracked events with optional filtering and pagination.

Parameter	Type	Required	Description
`eventName`	`string`	No	Filter by event name
`userId`	`string`	No	Filter by user ID
`preset`	`string`	No	Date preset
`from` / `to`	`string`	No	Explicit date range (`YYYY-MM-DD`)
`timezone`	`string`	No	Timezone (default: `UTC`)
`page`	`number`	No	Page number (0-indexed)
`size`	`number`	No	Page size
`sort`	`string`	No	Sort order (`asc` or `desc`)

`get_event_stats`

Returns aggregated event counts, a timeline, and an optional breakdown by a property.

Parameter	Type	Required	Description
`eventName`	`string`	No	Filter by event name
`preset`	`string`	No	Date preset
`from` / `to`	`string`	No	Explicit date range (`YYYY-MM-DD`)
`timezone`	`string`	No	Timezone (default: `UTC`)
`breakdownProperty`	`string`	No	Property to break down by

Users

Tool	Description
`list_users`	List or search users in the project
`get_user_summary`	Comprehensive analytics summary for a specific user (total events, first/last seen, top events, etc.)
`get_user_activity`	Daily activity heatmap data for a specific user over the last N months
`get_user_events`	Paginated event list for a specific user

`list_users`

Lists users with optional search and date filtering.

Parameter	Type	Required	Description
`search`	`string`	No	Search query (matches name, email, or user ID)
`preset`	`string`	No	Date preset
`from` / `to`	`string`	No	Explicit date range (`YYYY-MM-DD`)
`timezone`	`string`	No	Timezone (default: `UTC`)
`page`	`number`	No	Page number (0-indexed)
`size`	`number`	No	Page size

`get_user_summary`

Returns a comprehensive analytics summary for a specific user, including total events, first/last seen timestamps, and top events.

Parameter	Type	Required	Description
`userId`	`string`	Yes	The user ID to look up
`type`	`string`	Yes	Whether the user is `identified` or `anonymous`

`get_user_activity`

Returns daily activity heatmap data for a specific user over a configurable number of months. Useful for visualizing how active a user has been over time.

Parameter	Type	Required	Description
`userId`	`string`	Yes	The user ID to look up
`type`	`string`	Yes	Whether the user is `identified` or `anonymous`
`months`	`number`	No	Number of months of activity to return (default: `4`)

`get_user_events`

Returns a paginated list of events for a specific user.

Parameter	Type	Required	Description
`userId`	`string`	Yes	The user ID to look up
`type`	`string`	Yes	Whether the user is `identified` or `anonymous`
`page`	`number`	No	Page number (0-indexed)
`size`	`number`	No	Page size (default: `20`)

Sessions

Tool	Description
`list_sessions`	List sessions with optional filtering
`get_session_detail`	Detailed session info including all events in the session

`list_sessions`

Lists sessions with optional date filtering, pagination, and sorting.

Parameter	Type	Required	Description
`preset`	`string`	No	Date preset
`from` / `to`	`string`	No	Explicit date range (`YYYY-MM-DD`)
`timezone`	`string`	No	Timezone (default: `UTC`)
`page`	`number`	No	Page number (0-indexed)
`size`	`number`	No	Page size
`sort`	`string`	No	Sort order (`asc` or `desc`)

`get_session_detail`

Returns detailed information about a single session, including every event in that session.

Parameter	Type	Required	Description
`sessionId`	`string`	Yes	The session ID

Funnels

Tool	Description
`analyze_funnel`	Analyze a conversion funnel with ordered steps and get conversion rates between each step

`analyze_funnel`

Define a multi-step funnel and get conversion rates between each step.

Parameter	Type	Required	Description
`steps`	`object[]`	Yes	Ordered funnel steps (minimum 2). Each step has `eventName` (string, required) and `filters` (string[], optional)
`preset`	`string`	No	Date preset
`from` / `to`	`string`	No	Explicit date range (`YYYY-MM-DD`)
`timezone`	`string`	No	Timezone (default: `UTC`)

Journeys

Tool	Description
`analyze_journeys`	Analyze user navigation paths showing common routes through pages or events

`analyze_journeys`

Analyzes common navigation paths users take, optionally scoped to a start and/or end page.

Parameter	Type	Required	Description
`startPage`	`string`	No	Starting page path to analyze journeys from
`endPage`	`string`	No	Ending page path to analyze journeys to
`preset`	`string`	No	Date preset
`from` / `to`	`string`	No	Explicit date range (`YYYY-MM-DD`)
`timezone`	`string`	No	Timezone (default: `UTC`)
`depth`	`number`	No	Maximum path depth to analyze

Frustration Signals

Tool	Description
`get_frustration_report`	Frustration signals report (rage clicks, dead clicks) with top frustrated pages and elements

`get_frustration_report`

Returns a frustration signals report including rage clicks and dead clicks, with the top pages and elements where users showed frustration.

Parameter	Type	Required	Description
`preset`	`string`	No	Date preset — see Date Filtering
`from` / `to`	`string`	No	Explicit date range (`YYYY-MM-DD`)
`timezone`	`string`	No	Timezone (default: `UTC`)
`limit`	`number`	No	Max number of top pages/elements to return (default: `10`)

Common Parameters

Date Filtering

Most tools accept date filtering via either a preset or an explicit date range:

preset — one of last_30_minutes, last_hour, today, yesterday, last_7_days, last_30_days, this_month, this_year
from / to — explicit date range in YYYY-MM-DD format
timezone — timezone for date calculations (default: UTC)

If both a preset and explicit dates are provided, the explicit dates take precedence.

Pagination

List endpoints support pagination:

page — page number (0-indexed)
size — number of items per page

Filters

Web analytics tools support filters in the format dimension:operator:values:

"country:is:US"
"browser:is:Chrome"
"page:contains:/blog"

Pass multiple filters as an array to combine them.

Example Prompts

Once connected, you can ask your AI assistant questions like:

Question	Tools Used
"How many visitors did we get last week?"	`get_web_summary`
"What are our top pages by pageviews this month?"	`get_web_breakdown`
"Show me the traffic trend for the past 30 days"	`get_web_timeline`
"What countries are our users coming from?"	`get_web_breakdown`
"Compare this week's traffic to last week by country"	`compare_periods`
"How many signup events happened today?"	`get_event_stats`
"Show me the signup funnel conversion rate"	`analyze_funnel`
"What's the most common user journey from the homepage?"	`analyze_journeys`
"Find sessions for user john@example.com"	`list_users` + `list_sessions`
"Show me a summary of user U-123's activity"	`get_user_summary`
"What has user U-123 been doing the last 4 months?"	`get_user_activity`
"List the recent events for user U-123"	`get_user_events`
"Which pages have the most rage clicks this week?"	`get_frustration_report`

Requirements

Node.js 18+
A Kitbase private API key (sk_kitbase_)

MCP Server ​

Installation ​

Configuration ​

Client Setup ​

Claude Code ​

Cursor ​

Other MCP Clients ​

Available Tools ​

Web Analytics ​

get_web_summary ​

get_web_timeline ​

get_web_breakdown ​

compare_periods ​

Events ​

list_events ​

get_event_stats ​

Users ​

list_users ​

get_user_summary ​

get_user_activity ​

get_user_events ​

Sessions ​

list_sessions ​

get_session_detail ​

Funnels ​

analyze_funnel ​

Journeys ​

analyze_journeys ​

Frustration Signals ​

get_frustration_report ​

Common Parameters ​

Date Filtering ​

Pagination ​

Filters ​

Example Prompts ​

Requirements ​

MCP Server

Installation

Configuration

Client Setup

Claude Code

Cursor

Other MCP Clients

Available Tools

Web Analytics

`get_web_summary`

`get_web_timeline`

`get_web_breakdown`

`compare_periods`

Events

`list_events`

`get_event_stats`

Users

`list_users`

`get_user_summary`

`get_user_activity`

`get_user_events`

Sessions

`list_sessions`

`get_session_detail`

Funnels

`analyze_funnel`

Journeys

`analyze_journeys`

Frustration Signals

`get_frustration_report`

Common Parameters

Date Filtering

Pagination

Filters

Example Prompts

Requirements