roblox-analytics-mcp

一个本地 MCP 服务器，通过 Open Cloud Analytics Query API 为 AI 代理提供对您的 Roblox 体验分析数据的只读访问。

它公开了 API 支持的全部 168 个指标，涵盖 16 个类别——留存、参与度、变现、获取、性能、经济、漏斗、自定义事件、缩略图、匹配、数据存储、安全和广告——外加一层分析工具，将“我的游戏表现如何？”转化为一次调用。

为什么不直接调用 API

原始 API 难以驱动：

• 指标名称、粒度和维度区分大小写，在运行时不可发现，并且每个无效组合都返回相同的模糊 400 / 2001。

• 每个账户每分钟只有 30 次查询，因此一次浪费的调用代价高昂。

• 大型查询返回 202 和一个需要轮询的路径。

• 没有活动的存储桶会被省略，而不是返回为零，因此间隙是模糊的。

• 漏斗步骤和产品 ID 必须先被发现，然后才能进行过滤。

此服务器处理了所有这些：它在花费查询之前根据捆绑的目录验证请求，在速率限制下自我调节，将长时间运行的操作跟踪到完成，明确报告缺失的存储桶而不是虚构零，并为您完成两阶段漏斗查找。

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、密钥的作用域、是否启用且未过期，以及它覆盖哪些 universe（* 表示所有者可以访问的每个体验）。

该用户 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 个群组大约需要一分钟；热查找是即时的。缓存是按所有者进行的，因此只有被速率限制的群组列表会在下次重试。

任何无法读取的来源都会在 errors 中报告，而不是被丢弃——带有错误出现的空结果意味着扫描被节流，而不是创建者没有游戏。否则这两种状态看起来相同，混淆它们会产生自信的错误答案。

值得了解的事情

聚合是报告的，而不是假设的。 将一个月内的每日活跃用户相加并不能得到月度活跃用户——它会重复计算任何玩过两次的人。在 API 支持的地方，期间总计来自单个全范围查询（aggregation: "api-period-total"）；在不支持的地方，回退标记为 mean-of-buckets 或 sum-of-buckets，因此数字永远不会是匿名的。

sum 并不总是有意义的。 每个结果都带有 aggregationHint。对于比率、平均值和百分位数（ForwardD1Retention、ClientFpsP90、PayingUsersCVR），它读作 average-only——sum 字段是算术的，而不是信息。

间隙不是零。 API 会省略没有活动的存储桶。结果报告 missingBuckets 列表，而不是填充会拉低平均值的零。

时间是 UTC。 endTime 是排他的，默认为今天的 UTC 午夜，因此您只会得到完整的存储桶。传递 endTime: "now" 以包含部分当前日期。范围接受 RFC 3339、普通日期或相对简写（-30d、-12w、-6mo、today、yesterday），或使用 lastDays。

留存窗口不同。 标准指标保留 4 年；性能和稳定性指标仅保留 28 天。超出窗口的查询会在本地被拒绝，并显示最早可查询的时间戳。

Beta 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