roblox-analytics-mcp

Open Cloud Analytics Query APIを通じて、AIエージェントにRoblox体験のアナリティクスへの読み取りアクセスを提供するローカルMCPサーバーです。

APIがサポートする168のメトリクスすべてを16カテゴリ（リテンション、エンゲージメント、マネタイゼーション、獲得、パフォーマンス、エコノミー、ファネル、カスタムイベント、サムネイル、マッチメイキング、データストア、セーフティ、広告）にわたって公開するほか、「私のゲームの調子はどう？」を1回の呼び出しに変える分析ツールのレイヤーも備えています。

なぜAPIを直接呼び出さないのか

生のAPIは操作が面倒です：

• メトリクス名、粒度、ディメンションは大文字小文字を区別し、実行時に発見できず、無効な組み合わせはすべて同じ不透明な400 / 2001を返します。

• アカウントごとに毎分30クエリという制限があるため、無駄な呼び出しは高くつきます。

• 大きなクエリは202とポーリングが必要なパスを返します。

• アクティビティのないバケットはゼロとして返されるのではなく省略されるため、ギャップがあいまいになります。

• ファネルのステップとプロダクトIDは、フィルタリングする前に発見する必要があります。

このサーバーはそれらすべてを処理します：クエリを消費する前にバンドルされたカタログに対してリクエストを検証し、レート制限内でペースを調整し、長時間実行されるオペレーションを完了まで追跡し、ゼロを捏造する代わりに欠落バケットを明示的に報告し、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. アクセス許可の下に、クエリしたい各体験を追加します。

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": "..." }

キーはボディで送信され、呼び出しには独自のスコープは不要です — 有効なキーならどれでも自己イントロスペクトできます。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で報告されます — エラーがある空の結果は、スキャンがスロットリングされたことを意味し、クリエイターにゲームがないことを意味するわけではありません。この2つの状態はそれ以外では同一に見え、混同すると自信満々の誤った答えを生み出します。

知っておくべきこと

集計は報告され、推測されません。 月間のデイリーアクティブユーザーを合計しても月間アクティブ数にはなりません — 2回プレイした人は二重にカウントされるからです。APIがサポートする場合、期間合計は単一の全範囲クエリ（aggregation: "api-period-total"）から得られます。サポートしない場合、フォールバックはmean-of-bucketsまたはsum-of-bucketsとラベル付けされ、数値が匿名になることはありません。

sumは常に意味があるわけではありません。 すべての結果にはaggregationHintが付きます。レート、平均、パーセンタイル（ForwardD1Retention、ClientFpsP90、PayingUsersCVR）ではaverage-onlyと表示されます — sumフィールドは算術的なもので、情報ではありません。

ギャップはゼロではありません。 APIはアクティビティのないバケットを省略します。結果は平均を引き下げるゼロを埋めるのではなく、missingBucketsリストを報告します。

時間はUTCです。 endTimeは排他的で、デフォルトは今日のUTC午前0時なので、完全なバケットのみが得られます。現在の部分的な日を含めるには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