Vexo

A Model Context Protocol server for the Vexo analytics Export API. Ask Claude (or any MCP client) questions about your mobile app's events — event vocabulary, aggregated counts, per-day timelines, sessions, and raw event streams — using your own Vexo login.

Unofficial / community project. Not affiliated with, sponsored by, or endorsed by Vexo. "Vexo" is a trademark of its respective owner and is used here only to describe the service this tool connects to.

---

What it does (and doesn't)

Vexo's Export API is a single paginated event endpoint — there is no server-side filtering or query language and a hard limit of 5 requests per minute per app. So this connector is deliberately a set of purpose-built aggregation tools, not a general "run any query" interface or a bulk CSV exporter. It downloads events for a date window and aggregates them locally.

Practical consequence: keep date windows tight. A couple of hours or days returns quickly; a busy week can be dozens of pages and take several minutes because of the rate limit. The server throttles itself to stay within Vexo's limit and backs off on 429.

Tools

Tool	Purpose
vexo_get_event_names	Top 50 event names in a window — schema discovery.
vexo_count_events	Event counts over a range, optionally grouped by a dimension (any metadata key or top-level field) with cohort + event-name filters.
vexo_event_timeline	Per-day counts of specified events, optionally grouped — find the day behavior changes.
vexo_get_sessions	Recent session summaries: duration, screen/event counts, last screen.
vexo_get_recent_events	The most recent raw events for one entity, with full metadata.
vexo_overview	Totals + top breakdowns (event type, route, OS, device, country, app version).

A dimension is any top-level event field (deviceId, country, deviceSystemName, appVersion, route, sessionId, deviceModel, city, type) or any metadata key (e.g. worker_id, user_id). Set a default dimension with the group_key config so you don't have to pass it every time.

Installation

Option 1 — Claude Desktop (one-click)

1. Download vexo-mcp.mcpb from Releases.
2. Open it with Claude Desktop (or Settings → Extensions → Install Extension…).
3. Fill in your Vexo App ID, email, and password in the extension settings. The password is stored in your OS keychain.

Option 2 — Manual config (npx)

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "vexo": {
      "command": "npx",
      "args": ["-y", "@kishanssg/vexo-mcp"],
      "env": {
        "VEXO_APP_ID": "your-app-uuid",
        "VEXO_USER": "[email protected]",
        "VEXO_PASSWORD": "your-password",
        "VEXO_GROUP_KEY": "worker_id",
        "VEXO_API_BASE": "https://api.vexo.co",
        "VEXO_DEFAULT_LOOKBACK_DAYS": "30"
      }
    }
  }
}

VEXO_APP_ID, VEXO_USER, and VEXO_PASSWORD are required; the rest are optional.

Authentication

Vexo's Export API authenticates with email + password only — it exchanges them for a short-lived token via POST /users/implicit/login. Vexo does not issue export API keys, so there is no key-auth mode. (The SDK key embedded in an app for sending events is unrelated and won't work here.) Your credentials are used solely to obtain that token; they are never logged or bundled.

Example prompts

• "Using vexo, list the top event names from 2026-06-01 to 2026-06-07."
• "Compare worker_shift_feed_viewed counts for workers 54, 111, and 2716 over the last two weeks."
• "Show a daily timeline of worker_shift_feed_viewed for worker 54 from 2026-05-01 to 2026-06-01 — when did it stop?"
• "Give me the 20 most recent sessions for worker 54 and flag the short ones."
• "Pull the last 10 raw events for worker 54."

Development

git clone https://github.com/kishanssg/vexo-mcp.git
cd vexo-mcp
npm install
npm run build       # compile TypeScript -> build/
npm test            # vitest unit tests (no credentials needed)
npm run inspector   # exercise tools with the MCP Inspector

Build the installable bundle:

npm run mcpb:build  # produces vexo-mcp.mcpb

Security

• No secrets in the bundle. Credentials come only from your config / environment and (in Claude Desktop) live in your OS keychain.
• Read-only. It only reads events via Vexo's Export API; it never writes.

Privacy Policy

This connector collects no data. It has no backend, telemetry, or analytics. Your Vexo credentials and queries go directly from your machine to the Vexo API you configure (default https://api.vexo.co); results return only to your MCP client. Credentials are stored solely in your OS keychain (or your own config) and are never transmitted to the author or any third party; event data exists only transiently in memory while a tool call is answered. Full policy: PRIVACY.md.

License

MIT — see LICENSE. Unofficial community project; not affiliated with Vexo.