Skip to main content
Glama
aptabase-mcp

aptabase-mcp

by billylo1

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 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

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

Available Tools

17 tools
get_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

    A3.5/5.0

    Scored across 17 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI agents to query RevenueCat's subscription analytics API using natural language, retrieving metrics like MRR, churn, and revenue.
      3
      9 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      First-party web analytics MCP server for AI agents, providing 42 tools to query traffic, events, funnels, conversions, sources, and performance data.
      40
      45 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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.
      5
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      17
      2
      MIT