roblox-analytics-mcp

Un servidor MCP local que ofrece a un agente de IA acceso de lectura a las analíticas de tus experiencias de Roblox a través de la Open Cloud Analytics Query API.

Expone las 168 métricas que admite la API en 16 categorías — retención, interacción, monetización, adquisición, rendimiento, economía, embudos, eventos personalizados, miniaturas, emparejamiento, almacenes de datos, seguridad y anuncios —, además de una capa de herramientas de análisis que convierte "¿cómo está mi juego?" en una sola llamada.

¿Por qué no llamar directamente a la API?

La API bruta es incómoda de manejar:

• Los nombres de las métricas, las granularidades y las dimensiones distinguen entre mayúsculas y minúsculas, no se pueden descubrir en tiempo de ejecución y cualquier combinación no válida devuelve el mismo 400 / 2001 opaco.

• Dispones de 30 consultas por minuto por cuenta, así que una llamada desperdiciada es costosa.

• Las consultas grandes devuelven 202 y una ruta que debes ir sondeando.

• Los buckets sin actividad se omiten en lugar de devolverse como cero, por lo que los vacíos son ambiguos.

• Los pasos del embudo y los IDs de producto deben descubrirse antes de poder filtrar por ellos.

Este servidor se encarga de todo eso: valida las solicitudes contra un catálogo incorporado antes de gastar una consulta, se autolimita para no superar el límite de frecuencia, sigue las operaciones de larga duración hasta que terminan, informa explícitamente de los buckets que faltan en lugar de inventar ceros y hace por ti la búsqueda de embudo en dos pasos.

Related MCP server: Roblox Executor MCP

Configuración

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

Crea una clave de API en el Creator Dashboard:

1. Añade cada experiencia que quieras consultar en Access Permissions.

2. Concede la operación universe.analytics:read ­sobre el sistema universe-analytics.

Después, guárdala:

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

Una clave guardada tiene prioridad sobre la variable de entorno ROBLOX_API_KEY.

Registro con Claude

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

Herramientas

Descubrir qué se puede consultar

Leer datos

Análisis

Contexto

Identidad: cómo sabe el servidor de quién son los juegos

Las claves de API de Open Cloud son anónimas para los endpoints a los que llaman — ninguna respuesta de análisis revela al autor de la petición, y ningún permiso adicional de la clave cambia eso. El servidor resuelve la identidad a través de un endpoint aparte:

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

La clave viaja en el cuerpo y la llamada no necesita ningún graant propio: cualquier clave valida puede inspeccionarse a sí misma. Devuelve authorizedUserId, los alcances de la clave, si está activada y sin caducar, y qué universos cubre (* significa cada experiencia a la que el propietario puede acceder).

Ese ID de usuario desbloquea el resto mediante endpoints públicos: el nombre de usuario del propietario, sus experiencias personales y todos los grupos a los que pertenece. Escanear grupos es importante: los títulos de un estudio suelen vivir en un grupo al que el desarrollador solo pertenece, por lo que una búsqueda limitada a la cuenta personal pierde por completo los juegos reales.

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

La lista de grupos se guarda en caché durante 6 horas (ROBLOX_ANALYTICS_CACHE_TTL_MINUTES para cambiarlo, refresh: true para saltárselo). Un análisis en frío de 40 grupos tarda alrededor de un minuto; las lecturas con la caché caliente son instantáneas. La caché es por propietario, de modo que solo se reintenta a la próxima vez una lista de grupos que haya sido limitada por la frecuencia.

Cualquier fuente que no se haya podido leer se notifica en errors en lugar de omitirse; un resultado vacío con errores significa que el escaneo se restringio, no que el creador no tenga juegos. Esos dos estados, por lo demás, parecen idénticos, y confundirlos produce respuestas erróneas con total seguridad.

Cosas que merece la pena saber

La agregación se informa, no se asume. Sumar usuarios activos diarios a lo largo de un mes no da los usuarios activos del mes; cuenta dos veces a cualquiera que haya jugado más de una vez. Cuando la API lo admite, los totales del período proceden de una única consulta para todo el rango (aggregation: "api-period-total"); cuando no, la alternativa se etiqueta mean-of-buckets o sum-of-buckets, de modo que la cifra nunca sea anónima.

sum no siempre es significativo. Todos los resultados llevan una aggregationHint. Para tasas, medias y percentiles (ForwardD1Retention, ClientFpsP90, PayingUsersCVR) el valor es average-only; el campo sum es aritmético, pero no informativo.

Los vacías no son ceros. La API omite los buckets sin actividad. Se notifica con una lista missingBuckets— que rellenando con ceros que bajarían los promedios o medios.

La hora es UTC. endTime es exclusivo y por defecto la medianoche UTC de hoy, por lo que solo se obtienen buckets completos. Pasa endTime: "now" para incluir el día actual parcial. Los rangos aceptan RFC 3339, fechas con texto simple o abre variaciones relativas (-30d, -12w, -6mo, today, yesterday), o se puede usar lastDays.

Las ventanas de retención no son iguales. Las métricas estándar conservan los datos durante 4 años; las métricas de rendimiento y estabilidad solo durante 28 días. Las consultas fuera de esa ventana se rechazan localmente con el mayor antiguo de datos consultable.

API beta. La API Analytics Query API se encuentra en beta y su esquema puede cambiar. El catálogo de métricas se genera a partir de la documentación oficial — actualízalo con npm run generate:catalog si Roblox añade métricas.

Desarrollo

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

Los tests simulan fetch para las suites orientadas a la API, así que solo la suite del protocolo MCP toca la red (endpoints públicos, sin necesidad de clave).

Licencia

MIT