roblox-analytics-mcp

AI 에이전트가 Open Cloud Analytics Query API를 통해 Roblox 경험 분석 데이터를 읽을 수 있게 해주는 로컬 MCP 서버입니다.

API가 지원하는 168개 지표를 16개 카테고리(리텐션, 참여, 수익화, 획득, 성능, 경제, 퍼널, 커스텀 이벤트, 썸네일, 매치메이킹, 데이터 스토어, 안전, 광고)에 걸쳐 모두 노출하며, "내 게임은 어떻게 돌아가고 있나?"라는 질문을 단 한 번의 호출로 해결하는 분석 도구 레이어도 함께 제공합니다.

API를 직접 호출하지 않는 이유

원시 API는 다루기가 까다롭습니다:

• 지표 이름, 세분화(granularity), 차원(dimension)은 대소문자를 구분하며 런타임에 알아낼 수 없고, 잘못된 조합은 모두 동일한 불투명한 400 / 2001 오류를 반환합니다.

• 분당 계정당 30회 쿼리로 제한되므로, 낭비되는 호출은 비용이 큽니다.

• 대규모 쿼리는 202와 폴링해야 하는 경로를 반환합니다.

• 활동이 없는 버킷은 0으로 반환되지 않고 생략되므로, 빈 구간이 모호합니다.

• 퍼널 단계와 제품 ID는 필터링에 사용하려면 먼저 알아내야 합니다.

이 서버는 그 모든 것을 처리합니다. 쿼리를 소모하기 전에 번들된 카탈로그를 기준으로 요청을 검증하고, 속도 제한 아래에서 스스로 페이스를 조절하며, 오래 걸리는 작업을 완료까지 추적하고, 0을 임의로 채우는 대신 누락된 버킷을 명시적으로 보고하며, 2단계 퍼널 조회를 대신 수행합니다.

Related MCP server: Roblox Executor MCP

설정

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

Creator Dashboard에서 API 키를 생성하세요:

1. Access Permissions 아래에 쿼리하려는 각 경험을 추가하세요.

2. universe-analytics 시스템에서 universe.analytics:read 작업을 부여하세요.

그런 다음 키를 저장하세요:

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

저장된 키는 ROBLOX_API_KEY 환경 변수보다 우선합니다.

Claude Code에 등록

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

도구

쿼리 가능한 항목 찾기

데이터 읽기

분석

컨텍스트

신원: 서버가 이 게임들이 누구의 것인지 아는 방법

Open Cloud API 키는 호출하는 엔드포인트에 대해 익명입니다 — 어떤 분석 응답도 호출자를 밝히지 않으며, 추가 키 권한으로도 그 점은 바뀌지 않습니다. 서버는 대신 별도의 엔드포인트를 통해 신원을 확인합니다:

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

키는 *본문(body)*에 담겨 전송되며, 이 호출에는 자체 스코프가 필요 없습니다 — 유효한 키라면 누구나 자신을 조회할 수 있습니다. 응답에는 authorizedUserId, 키의 스코프, 활성화 상태와 만료 여부, 그리고 키가 적용되는 유니버스 목록이 포함됩니다(*는 소유자가 접근할 수 있는 모든 경험을 의미합니다).

그 사용자 ID는 공개 엔드포인트를 통해 나머지 정보를 열어줍니다: 소유자의 사용자 이름, 개인 경험, 그리고 소속된 모든 그룹. 그룹 스캔이 중요한 이유 — 스튜디오 타이틀은 대개 개발자가 단순히 소속된 그룹 아래에 있으므로, 개인 계정만 조회하면 실제 게임을 완전히 놓치게 됩니다.

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

그룹 목록은 6시간 동안 캐시됩니다(변경하려면 ROBLOX_ANALYTICS_CACHE_TTL_MINUTES, 우회하려면 refresh: true). 40개 그룹의 콜드 스캔은 약 1분이 걸리며, 웜 조회는 즉시 이루어집니다. 캐싱은 소유자별로 이루어지므로, 속도 제한에 걸린 그룹 목록만 다음에 다시 시도됩니다.

읽을 수 없는 소스는 삭제되지 않고 errors에 보고됩니다 — 오류가 있는 빈 결과는 스캔이 제한(throttled)되었음을 의미하지, 제작자에게 게임이 없다는 뜻이 아닙니다. 이 두 상태는 그 외에는 동일해 보이므로, 이를 혼동하면 자신 있게 틀린 답을 만들어냅니다.

알아두면 좋은 점

집계는 가정하지 않고 보고됩니다. 한 달 동안의 일일 활성 사용자를 합산한다고 월간 활성 사용자가 나오지 않습니다 — 두 번 플레이한 사용자는 두 번 집계되기 때문입니다. API가 지원하는 경우 기간 합계는 단일 전체 범위 쿼리(aggregation: "api-period-total")로 얻어지며, 지원하지 않는 경우에는 mean-of-buckets 또는 sum-of-buckets로 표시되어 숫자가 익명이 되지 않습니다.

sum이 항상 의미 있는 것은 아닙니다. 모든 결과에는 aggregationHint가 포함됩니다. 비율, 평균, 백분위수(ForwardD1Retention, ClientFpsP90, PayingUsersCVR)의 경우 average-only로 표시됩니다 — sum 필드는 산술적일 뿐 정보가 아닙니다.

빈 구간은 0이 아닙니다. API는 활동이 없는 버킷을 생략합니다. 결과는 평균을 끌어내릴 0을 채우는 대신 missingBuckets 목록을 보고합니다.

시간은 UTC입니다. endTime은 종료 시각을 포함하지 않으며 기본값은 오늘 UTC 자정이므로 완전한 버킷만 얻을 수 있습니다. 현재 진행 중인 부분적인 날짜를 포함하려면 endTime: "now"를 전달하세요. 범위는 RFC 3339, 일반 날짜, 상대 약어(-30d, -12w, -6mo, today, yesterday)를 허용하며, lastDays를 사용할 수도 있습니다.

리텐션 기간이 다릅니다. 표준 지표는 4년을 유지하고, 성능 및 안정성 지표는 28일만 유지합니다. 기간을 벗어난 쿼리는 쿼리 가능한 가장 이른 타임스탬프와 함께 로컬에서 거부됩니다.

베타 API. Analytics Query API는 베타 상태이며 스키마가 변경될 수 있습니다. 지표 카탈로그는 공식 문서에서 생성됩니다 — Roblox가 지표를 추가하면 npm run generate:catalog로 새로고침하세요.

개발

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

테스트는 API 관련 스위트에서 fetch를 모킹하므로, 네트워크에 접근하는 것은 MCP 프로토콜 스위트뿐입니다(공개 엔드포인트, 키 불필요).

라이선스

MIT