aptabase-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@aptabase-mcp Show key metrics for my app over the last 7 days."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Aptabase MCP Server
Unofficial TypeScript MCP server that lets AI agents (Cursor, Claude Desktop, etc.) query Aptabase analytics.
Aptabase has no public query API. This server wraps the same cookie-authenticated dashboard endpoints used by the web UI (/api/_apps, /api/_stats/*, /api/_export/usage). Those endpoints are undocumented and may change.
Security
APTABASE_AUTH_SESSION is a full dashboard login cookie. Anyone with it can read your analytics (and anything else that session can do in the Aptabase UI).
Store it only in local MCP config or a secret manager — never commit it.
Prefer a throwaway / limited account if your org supports one.
Rotate by signing out of Aptabase (or clearing the cookie) if it leaks.
Do not paste real cookies into issues, PRs, or chat logs.
Related MCP server: @lodd/mcp-server
Requirements
Node.js 20+
An Aptabase account (cloud US/EU or self-hosted)
A browser session cookie named
auth-session
Install (Cursor)
Clone and build:
git clone https://github.com/billylo1/aptabase-mcp.git
cd aptabase-mcp
npm installAdd to Cursor MCP settings (~/.cursor/mcp.json or project .cursor/mcp.json):
{
"mcpServers": {
"aptabase": {
"command": "node",
"args": ["/absolute/path/to/aptabase-mcp/dist/index.js"],
"env": {
"APTABASE_BASE_URL": "https://us.aptabase.com",
"APTABASE_AUTH_SESSION": "<paste-cookie-value>"
}
}
}
}For local development without building:
{
"mcpServers": {
"aptabase": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/aptabase-mcp/src/index.ts"],
"env": {
"APTABASE_BASE_URL": "https://us.aptabase.com",
"APTABASE_AUTH_SESSION": "<paste-cookie-value>"
}
}
}
}Get the auth-session cookie
Log into Aptabase (
https://us.aptabase.com,https://eu.aptabase.com, or your self-hosted URL).Open DevTools → Application (Chrome) / Storage (Firefox) → Cookies.
Copy the value of
auth-session(not the name).Paste into
APTABASE_AUTH_SESSION. Cookies last up to ~365 days; refresh on 401.
Base URL
Deployment |
|
Aptabase Cloud (US) |
|
Aptabase Cloud (EU) |
|
Self-hosted |
|
Use the same host you logged into when copying the cookie.
Tools
Tool | Description |
| List apps for the authenticated account |
| Get one app by id |
| Key metrics (daily users, sessions, events, duration) |
| Time-series buckets |
| Top event names |
| Top countries |
| Top operating systems |
| Top OS versions |
| Top app versions |
| Top device models |
| Top regions |
| Custom props for a given |
| Recent/live sessions |
| Live geo points |
| Session timeline |
| Historical sessions |
| Monthly event counts |
Most stats tools accept:
appId(required)buildMode:release(default) ordebugperiodpreset orstartDate/endDate(ISO)Optional filters:
eventName,osName,appVersion,countryCode,deviceModel
Period presets
Same as the Aptabase dashboard: 24h, 48h, today, yesterday, 7d, 14d, 30d, month, last-month, 90d, 180d, 365d, all.
If neither period nor dates are provided, stats tools default to 24h.
Note: dailyUsers from get_metrics is average daily users for the window, not a multi-day distinct user total (Aptabase’s privacy model).
Example prompts
“List my Aptabase apps.”
“Show key metrics for app
<appId>over the last 7 days.”“What are the top events in the last 30 days for
<appId>?”“Break down properties for the
purchaseevent over the last 90 days.”“Show live sessions and then detail session
<sessionId>.”
Scripts
Script | Purpose |
| Install deps and build ( |
| Run with |
| Compile to |
| Run |
| Unit tests |
|
|
Notes
Read-only: does not create/update/delete apps or download bulk CSV exports.
Dashboard stats are rate-limited (~1000 req/hour); retry on
429.App Key (
A-US-…) is for ingestion only — querying needs theauth-sessioncookie.Not affiliated with Aptabase.
License
MIT
Available Tools
17 toolsget_appA
Get a single Aptabase app by id.
Inputs: appId (required).
get_event_propsC
Breakdown of custom string/numeric properties for a specific event name. Requires eventName.
Inputs: appId (required), eventName (required), osName, period, +7 more.
get_historical_sessionsC
Historical sessions for an app over a period, with optional filters.
Inputs: appId (required), osName, period, endDate, +8 more.
get_live_geoC
Live geographic distribution of current users for an app.
Inputs: appId (required), buildMode.
get_live_sessionsB
Recent/live sessions currently active for an app.
Inputs: appId (required), buildMode.
get_metricsA
Key metrics for an app over a period: daily users, sessions, events, avg duration. Includes previous-period comparison when a date range is set.
Inputs: appId (required), osName, period, endDate, +7 more.
get_monthly_usageB
Monthly event usage counts for billing/quota (year, month, events).
Inputs: appId (required), buildMode.
get_periodic_statsA
Time-series stats (users, sessions, events) bucketed by hour/day/month for charts.
Inputs: appId (required), osName, period, endDate, +7 more.
get_session_detailsA
Session timeline details (events, props, device/geo metadata) for a session id.
Inputs: appId (required), sessionId (required), buildMode.
get_top_app_versionsB
Top app versions by unique sessions for the period.
Inputs: appId (required), osName, period, endDate, +7 more.
get_top_countriesC
Top countries by unique sessions for the period.
Inputs: appId (required), osName, period, endDate, +7 more.
get_top_devicesB
Top device models by unique sessions for the period.
Inputs: appId (required), osName, period, endDate, +7 more.
get_top_eventsB
Top event names by total event count for the period.
Inputs: appId (required), osName, period, endDate, +7 more.
get_top_osB
Top operating systems by unique sessions for the period.
Inputs: appId (required), osName, period, endDate, +7 more.
get_top_os_versionsB
Top OS versions by unique sessions for the period.
Inputs: appId (required), osName, period, endDate, +7 more.
get_top_regionsC
Top regions by unique sessions for the period.
Inputs: appId (required), osName, period, endDate, +7 more.
list_appsA
List Aptabase apps available to the authenticated account (id, name, appKey, ownership).
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool targets a distinct query or resource: app metadata, metrics, time series, top lists, live sessions, and session details. Even similar tools like get_top_countries and get_top_regions differ in granularity and purpose.
All tools follow the get_<noun> pattern, with lowercase snake_case and no style mixing. The naming is uniform and predictable, making it easy to infer each tool's purpose.
At 17 tools, the server is slightly above the ideal 3-15 range, but each tool targets a specific analytics need and none feel redundant. The count is justified for the scope of an analytics server.
The tool set covers app listing, core metrics, periodic statistics, top dimension breakdowns, event properties, live sessions, and historical session detail. This is a comprehensive analytics surface with no obvious dead ends for the stated domain.
Maintenance
Related MCP Connectors
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
Analytics for MCP servers. Find out which of your tools agents get wrong. MCPulse shows you which tools AI agents retry, which come back empty, and which they never call at all. Two lines inside your own server. It never sees your arguments or your results. getmcpulse.com
Clamp Analytics MCP server: traffic, revenue, funnels, cohorts, errors, and search, for AI agents.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables AI agents to query RevenueCat's subscription analytics API using natural language, retrieving metrics like MRR, churn, and revenue.39 npmMIT
- AlicenseAqualityDmaintenanceFirst-party web analytics MCP server for AI agents, providing 42 tools to query traffic, events, funnels, conversions, sources, and performance data.4045 npmMIT
- AlicenseNot gradedqualityBmaintenanceMCP server that provides product and web analytics capabilities, allowing AI coding assistants to query funnels, retention, trends, feature flags, A/B tests, and more in natural language.5MIT

Aptabase MCP Serverofficial
AlicenseBqualityDmaintenanceEnables AI agents to query Aptabase analytics through MCP, including metrics, top events, countries, sessions, and more. Uses the dashboard's cookie-authenticated endpoints, so it requires an Aptabase auth session cookie.172MIT