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: Gizmo Analytics

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

1. Log into Aptabase (https://us.aptabase.com, https://eu.aptabase.com, or your self-hosted URL).

2. Open DevTools → Application (Chrome) / Storage (Firefox) → Cookies.

3. Copy the value of auth-session (not the name).

4. Paste into APTABASE_AUTH_SESSION. Cookies last up to ~365 days; refresh on 401.

Base URL

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

Tools

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

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