roblox-analytics-mcp

Локальный MCP-сервер, который даёт ИИ-агенту доступ на чтение к аналитике вашего опыта в Roblox через Open Cloud Analytics Query API.

Он предоставляет все 168 метрик, поддерживаемых API, в 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

Создайте API-ключ в Creator Dashboard:

1. Добавьте каждый опыт, который хотите запрашивать, в разделе Access Permissions.

2. Предоставьте операцию universe.analytics:read в системе universe-analytics.

Затем сохраните его:

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

Инструменты

Обнаружение того, что можно запрашивать

Чтение данных

Анализ

Контекст

Идентификация: как сервер узнаёт, чьи это игры

API-ключи Open Cloud анонимны для вызываемых конечных точек — ни один ответ аналитики не раскрывает вызывающего, и никакие дополнительные разрешения ключа этого не меняют. Сервер определяет личность через отдельную конечную точку:

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 групп занимает около минуты; тёплые запросы мгновенны. Кэширование выполняется для каждого владельца, поэтому при следующем запросе повторяется только тот список групп, который был ограничен по скорости.

Любой источник, который не удалось прочитать, сообщается в 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 дней. Запросы за пределами окна отклоняются локально с указанием самой ранней доступной метки времени.

Бета-API. Analytics Query API находится в бете, и его схема может измениться. Каталог метрик генерируется из официальной документации — обновите его с помощью npm run generate:catalog, если Roblox добавит метрики.

Разработка

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

Тесты имитируют fetch для наборов, работающих с API, поэтому только набор протокола MCP касается сети (публичные конечные точки, ключ не нужен).

Лицензия

MIT