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.

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/aptabase/aptabase-mcp.git
cd aptabase-mcp
npm install

Add 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_BASE_URL`
Aptabase Cloud (US)	`https://us.aptabase.com`
Aptabase Cloud (EU)	`https://eu.aptabase.com`
Self-hosted	`https://your-host.example.com` (no trailing slash)

Use the same host you logged into when copying the cookie.

Tools

Tool	Description
`list_apps`	List apps for the authenticated account
`get_app`	Get one app by id
`get_metrics`	Key metrics (daily users, sessions, events, duration)
`get_periodic_stats`	Time-series buckets
`get_top_events`	Top event names
`get_top_countries`	Top countries
`get_top_os`	Top operating systems
`get_top_os_versions`	Top OS versions
`get_top_app_versions`	Top app versions
`get_top_devices`	Top device models
`get_top_regions`	Top regions
`get_event_props`	Custom props for a given `eventName`
`get_live_sessions`	Recent/live sessions
`get_live_geo`	Live geo points
`get_session_details`	Session timeline
`get_historical_sessions`	Historical sessions
`get_monthly_usage`	Monthly event counts

Most stats tools accept:

appId (required)
buildMode: release (default) or debug
period preset or startDate / 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 purchase event over the last 90 days.”
“Show live sessions and then detail session <sessionId>.”

Scripts

Script	Purpose
`npm install`	Install deps and build (`prepare`)
`npm run dev`	Run with `tsx` (no build)
`npm run build`	Compile to `dist/`
`npm start`	Run `dist/index.js`
`npm test`	Unit tests
`npm run typecheck`	`tsc --noEmit`

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 the auth-session cookie.
Not affiliated with Aptabase.

License

MIT