# Vexo MCP — Unofficial / Community

A [Model Context Protocol](https://modelcontextprotocol.io) server for the
**[Vexo](https://vexo.co) 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](https://github.com/kishanssg/vexo-mcp/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`):

```json
{
  "mcpServers": {
    "vexo": {
      "command": "npx",
      "args": ["-y", "@kishanssg/vexo-mcp"],
      "env": {
        "VEXO_APP_ID": "your-app-uuid",
        "VEXO_USER": "you@example.com",
        "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

```bash
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:

```bash
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](https://github.com/kishanssg/vexo-mcp/blob/master/PRIVACY.md).

## License

MIT — see [LICENSE](./LICENSE). Unofficial community project; not affiliated
with Vexo.