roblox-analytics-mcp

Ein lokaler MCP-Server, der einem KI-Agenten Lesezugriff auf deine Roblox-Experience-Analysen über die Open Cloud Analytics Query API gewährt.

Er stellt alle 168 Metriken bereit, die die API unterstützt, in 16 Kategorien – Retention, Engagement, Monetarisierung, Akquisition, Performance, Ökonomie, Funnels, benutzerdefinierte Events, Thumbnails, Matchmaking, Data Stores, Sicherheit und Werbung – plus eine Ebene von Analysetools, die „Wie läuft mein Spiel?" in einen einzigen Aufruf verwandeln.

Warum nicht einfach die API direkt aufrufen

Die rohe API ist umständlich zu bedienen:

• Metriknamen, Granularitäten und Dimensionen sind case-sensitiv, zur Laufzeit nicht auffindbar, und jede ungültige Kombination gibt denselben undurchsichtigen 400 / 2001 zurück.

• Du bekommst 30 Abfragen pro Minute pro Konto, also ist ein verschwendeter Aufruf teuer.

• Große Abfragen geben 202 und einen Pfad zurück, den du pollen musst.

• Buckets ohne Aktivität werden weggelassen statt als Null zurückgegeben, also sind Lücken mehrdeutig.

• Funnel-Schritte und Produkt-IDs müssen entdeckt werden, bevor sie gefiltert werden können.

Dieser Server übernimmt das alles: Er validiert Anfragen gegen einen gebündelten Katalog, bevor er eine Abfrage ausgibt, hält sich unter dem Rate-Limit, verfolgt langlaufende Operationen bis zum Abschluss, meldet fehlende Buckets explizit statt Nullen zu erfinden und führt die zweistufige Funnel-Suche für dich durch.

Related MCP server: Roblox Executor MCP

Einrichtung

npm install
npm run build
npm link          # optional, puts `roblox-analytics-mcp` on your PATH

Erstelle einen API-Schlüssel im Creator Dashboard:

1. Füge jede Experience, die du abfragen möchtest, unter Zugriffsberechtigungen hinzu.

2. Gewähre die Operation universe.analytics:read unter dem System universe-analytics.

Dann speichere ihn:

roblox-analytics-mcp setup     # prompts for the key and an optional default universe
roblox-analytics-mcp test      # runs a live DAU query to confirm it works

Ein gespeicherter Schlüssel hat Vorrang vor der Umgebungsvariable ROBLOX_API_KEY.

Bei Claude Code registrieren

claude mcp add roblox-analytics -- node /absolute/path/to/AnalyticsMcp/dist/cli.js

Tools

Was abfragbar ist

Daten lesen

Analyse

Kontext

Identität: Wie der Server weiß, wessen Spiele das sind

Open-Cloud-API-Schlüssel sind anonym gegenüber den Endpunkten, die sie aufrufen – keine Analyseantwort verrät den Aufrufer, und keine zusätzliche Schlüsselberechtigung ändert das. Der Server löst die Identität stattdessen über einen separaten Endpunkt auf:

POST https://apis.roblox.com/api-keys/v1/introspect   { "apiKey": "..." }

Der Schlüssel reist im Body, und der Aufruf benötigt keinen eigenen Scope – jeder gültige Schlüssel kann sich selbst introspizieren. Er gibt authorizedUserId, die Scopes des Schlüssels, ob er aktiviert und nicht abgelaufen ist, und welche Universen er abdeckt (* bedeutet jede Experience, auf die der Besitzer zugreifen kann).

Diese Benutzer-ID erschließt den Rest über öffentliche Endpunkte: den Benutzernamen des Besitzers, seine persönlichen Experiences und jede Gruppe, zu der er gehört. Gruppen-Scanning ist wichtig – Studio-Titel leben normalerweise unter einer Gruppe, zu der der Entwickler nur gehört, also übersieht eine Suche nur über das persönliche Konto die eigentlichen Spiele komplett.

whoami                                  → who owns this key, what can it read
find_universes { search: "party" }      → ranked matches across account + groups

Gruppenlisten werden 6 Stunden lang zwischengespeichert (ROBLOX_ANALYTICS_CACHE_TTL_MINUTES zum Ändern, refresh: true zum Umgehen). Ein kalter Scan von 40 Gruppen dauert etwa eine Minute; warme Abfragen sind sofort. Das Caching ist pro Besitzer, also wird nur eine Gruppenliste, die rate-limitiert wurde, beim nächsten Mal erneut versucht.

Jede Quelle, die nicht gelesen werden konnte, wird in errors gemeldet statt verworfen – ein leeres Ergebnis mit Fehlern bedeutet, dass der Scan gedrosselt wurde, nicht dass der Ersteller keine Spiele hat. Diese beiden Zustände sehen sonst identisch aus, und ihre Vermischung erzeugt selbstbewusst falsche Antworten.

Wissenswertes

Aggregation wird gemeldet, nicht angenommen. Das Summieren täglicher aktiver Benutzer über einen Monat ergibt nicht monatliche Aktive – es zählt jeden, der zweimal gespielt hat, doppelt. Wo die API es unterstützt, stammen Periodensummen aus einer einzigen Gesamtbereichsabfrage (aggregation: "api-period-total"); wo nicht, wird der Fallback als mean-of-buckets oder sum-of-buckets gekennzeichnet, damit die Zahl nie anonym ist.

sum ist nicht immer aussagekräftig. Jedes Ergebnis trägt einen aggregationHint. Für Raten, Durchschnitte und Perzentile (ForwardD1Retention, ClientFpsP90, PayingUsersCVR) lautet er average-only – das sum-Feld ist Arithmetik, keine Information.

Lücken sind keine Nullen. Die API lässt Buckets ohne Aktivität aus. Ergebnisse melden eine missingBuckets-Liste, statt Nullen einzufügen, die Durchschnitte nach unten ziehen würden.

Zeit ist UTC. endTime ist exklusiv und standardmäßig auf Mitternacht UTC heute gesetzt, also bekommst du nur vollständige Buckets. Übergib endTime: "now", um den teilweisen aktuellen Tag einzuschließen. Bereiche akzeptieren RFC 3339, einfache Daten oder relative Kurzformen (-30d, -12w, -6mo, today, yesterday) oder verwende lastDays.

Retentionsfenster unterscheiden sich. Standardmetriken behalten 4 Jahre; Performance- und Stabilitätsmetriken nur 28 Tage. Abfragen jenseits des Fensters werden lokal mit dem frühesten abfragbaren Zeitstempel abgelehnt.

Beta-API. Die Analytics Query API ist in der Beta und ihr Schema kann sich ändern. Der Metrikkatalog wird aus den offiziellen Dokumenten generiert – aktualisiere ihn mit npm run generate:catalog, wenn Roblox Metriken hinzufügt.

Entwicklung

npm run build             # compile TypeScript
npm test                  # 6 suites: time, validation, query pipeline, reports, packs, MCP protocol
npm run generate:catalog  # regenerate src/catalog.ts from the Roblox docs

Tests mocken fetch für die API-bezogenen Suiten, also berührt nur die MCP-Protokoll-Suite das Netzwerk (öffentliche Endpunkte, kein Schlüssel nötig).

Lizenz

MIT