# roblox-analytics-mcp

A local [MCP](https://modelcontextprotocol.io) server that lets AI agents (Claude Code, Codex, etc.)
query **Roblox experience analytics** — DAU, revenue, retention, playtime, crash rates, funnels,
custom events, data store usage, and more — through the
[Open Cloud Analytics API](https://create.roblox.com/docs/cloud/guides/analytics).

Runs entirely on your machine. Your API key is stored locally and never leaves your computer.

## Tools

| Tool | What it does |
| --- | --- |
| `list_metrics` | Browse the ~150 supported metrics with their exact names, categories, supported granularities, retention windows, and supported dimensions. Filter by category or keyword. |
| `query_metrics` | Query a metric time series for a universe: pick a granularity (`OneMinute` … `OneMonth`, or `None` for one total), a date range, optional `breakdown` dimensions and `filter`s. |
| `list_dimension_values` | Discover which values a dimension actually has (countries, platforms, funnel names, custom event names, place IDs, …) for a metric and date range. |
| `get_operation` | Poll a slow query that came back with `done: false`. |

Slow queries are polled automatically for up to 60 seconds (configurable via `pollTimeoutSeconds`).
If a query still isn't finished, the pending operation's `path` is returned so the agent can
call `get_operation` later.

### Metric categories

Retention, Engagement, Monetization, Acquisition, Performance, Economy, Funnels, CustomEvents,
Thumbnails, SpeechToText, TextToSpeech, Matchmaking, DataStore, MemoryStore, Safety, Advertising.

Standard metrics keep ~4 years of data; performance, data store, and memory store metrics keep 28 days;
matchmaking keeps 90 days. Ranges longer than two years only support `OneWeek`, `OneMonth`, or `None`.

### Example prompts

- "What was my DAU by platform for the last 30 days in universe 123456?"
- "Compare revenue by country for August vs September."
- "Which funnel steps have the highest churn in my onboarding funnel?"
- "Show client crash rate per hour for the last 24 hours, broken down by PlaceVersion."

## Setup

### 1. Get an Open Cloud API key

1. Go to the [Creator Dashboard → Open Cloud → API Keys](https://create.roblox.com/dashboard/credentials).
2. Create a key and add the **universe-analytics** API system.
3. Give it the `universe.analytics:read` scope for the universes you want to query.

This key only needs read access to analytics — nothing else.

### 2. Install

```bash
npm install -g @frrazers/roblox-analytics-mcp
```

(Or clone this repo and run `npm install && npm run build`, then use `node dist/cli.js` as the command.)

### 3. Store your key

```bash
roblox-analytics-mcp setup
```

This prompts for your key (hidden input) and saves it to your OS config directory.
No secrets end up in any shared config file. Check it worked with:

```bash
roblox-analytics-mcp status
```

### 4. Connect it to Claude Code

Either register it:

```bash
claude mcp add roblox-analytics -- roblox-analytics-mcp
```

or add a `.mcp.json` to your project (safe to commit — it contains no secret):

```json
{
  "mcpServers": {
    "roblox-analytics": {
      "command": "roblox-analytics-mcp"
    }
  }
}
```

The tools appear as `mcp__roblox-analytics__*` in your next session; `/mcp` shows status.

## Managing your key

| Command | Action |
| --- | --- |
| `roblox-analytics-mcp setup` | Store or replace the key |
| `roblox-analytics-mcp setup --clear` | Delete the stored key |
| `roblox-analytics-mcp status` | Show whether a key is configured and where it came from |

A key stored by `setup` takes precedence. If you haven't run `setup`, the `ROBLOX_API_KEY` environment variable is used as a fallback (handy for CI).

## Notes on the API

- Metric names are case-sensitive (`DailyActiveUsers`, not `dailyactiveusers`). The server warns you before sending if a name, granularity, or dimension doesn't match its local catalog, but still forwards the request in case the catalog is behind the live API.
- `startTime` is inclusive and `endTime` is exclusive, both RFC 3339 UTC.
- A 429 with code 3000 means the data-point budget was exceeded: shorten the range, coarsen the granularity, or reduce breakdowns.

## License

MIT