rbx-studio-mcp

Roblox Studio MCP

Deixe um agente de IA controlar o Roblox Studio: leia seu lugar, edite scripts, construa geometria, execute playtests, tire capturas de tela. 35 ferramentas. MIT.

Instalação

1. O plugin

npx -y @el4cteo/rbx-studio-mcp --install-plugin

Ou coloque StudioMCP.rbxmx de Releases na sua pasta de plugins do Studio.

2. O servidor

claude mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp

codex mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp

{
  "mcpServers": {
    "roblox-studio": {
      "command": "npx",
      "args": ["-y", "@el4cteo/rbx-studio-mcp"]
    }
  }
}

{
  "mcp": {
    "roblox-studio": {
      "type": "local",
      "command": ["npx", "-y", "@el4cteo/rbx-studio-mcp"],
      "enabled": true
    }
  }
}

3. Abra o Studio e aceite o prompt 127.0.0.1. Verifique se funciona com studio_status.

Algo errado? Execute npx -y @el4cteo/rbx-studio-mcp doctor — ele diz o que está quebrado e como corrigir.

A porta é 44755, apenas loopback. Altere com --port e ajuste no plugin.

Ferramentas

Ferramentas de escrita aceitam arrays — dez edições de script é uma chamada, um Ctrl+Z, e tudo ou nada.

Inspecione o cliente em execução

Durante um playtest, os leitores podem rodar na própria VM do jogador (use o studioId do servidor de playtest; adicione player="Name" com vários jogadores):

tree target="client" path="Players.Alice.PlayerGui" handles=true
inspect target="client" paths=["<handle>"] properties=["Text","AbsoluteSize"]
find target="client" className="TextButton"
viewport op="ui" target="client"
viewport op="pick" x=0.5 y=0.5 target="client"
performance op="snapshot" target="client"
debug op="watch" path=... target="client" properties=["Text"] seconds=5
debug op="collisions" path="Workspace.Ball" minSpeed=5 seconds=5

• Handles (handles=true) são referências de sessão que substituem caminhos. Eles sobrevivem a renomeações e movimentações, e falham em vez de apontar para o objeto errado quando excluídos ou expirados.
• pick retorna o objeto sob um ponto da tela (normalizado sobre o viewport inteiro).
• watch registra mudanças de propriedades, atributos e filhos por 1-15 segundos. Envie entrada em paralelo para ver uma reação.
• collisions relata o que uma peça, ou cada peça em um modelo, atingiu: ponto de contato, normal, velocidade de impacto e área, do mais forte ao mais fraco. Precisa de um playtest em execução.
• Resultados de execute_luau recortados retornam um resultId. Navegue por ele com source omitido; nada é reexecutado. Os resultados são mantidos por 120 segundos.

Trabalhe com arquivos

sync espelha seus scripts em uma pasta, para que um agente possa editar código com suas próprias ferramentas de arquivo e usar o Studio para testar.

sync op="pull"      # Studio -> ./studio
sync op="push"      # ./studio -> Studio
sync op="watch"     # both ways, live, until op="stop"

• Layout estilo Rojo: Main.server.luau, .client.luau, .luau; um script com filhos é uma pasta com init. Um sourcemap.json é escrito para luau-lsp.
• Renomeie ou mova um arquivo e o script se move junto, mantendo seus atributos e referências.
• Editado nos dois lados? É um conflito e nenhum lado é tocado. A versão do Studio espera em .rbx-sync/conflicts/; mescle no arquivo e sincronize novamente, ou passe prefer: "studio" / "disk".
• Excluir um arquivo exclui o script (um Ctrl+Z). Um script excluído no Studio envia seu arquivo para .rbx-sync/trash.
• export escreve UI ou qualquer árvore de instâncias como um arquivo .build.json; edite-o e build o reconstrói, mantendo seus scripts. Edições feitas no Studio fluem de volta para o arquivo.
• watch só funciona quando algo muda: cerca de 0,5s em cada direção, mesmo com 2.000 scripts. Conflitos aparecem na próxima resposta do agente.

Open Cloud

Algumas chamadas alcançam além do Studio até o próprio Roblox. Todas precisam de uma chave de API; todo o resto funciona sem ela.

Crie uma chave em Creator Dashboard → Credentials, adicionando as permissões que desejar: assets, universe-datastores, ordered-data-stores, luau-execution-sessions, universe-places, universe-place-instances, universe, messaging-service, user-restrictions, inventory, users, asset-permissions, developer-products, game-passes, universe-analytics. Agendar eventos precisa das permissões universe.event:read e :write.

Depois, no painel do Studio:

cloud key <paste>
cloud user <your user id>
cloud place <place id>

cloud place descobre o universo para você. A chave digitada é mascarada no log e no histórico, e armazenada em ~/.rbx-studio-mcp/credentials.json (modo 0600) — nunca no arquivo do lugar, nunca na conversa. cloud mostra o que está definido, cloud test verifica novamente, cloud forget exclui. ROBLOX_API_KEY e amigos no ambiente também funcionam e têm prioridade.

Duas coisas para observar: um playtest conecta uma segunda sessão, então passe studioId e use a sessão de edição para mudanças que devem durar; a emulação device permanece ativa até device op="stop".

O painel do console

Cada chamada é registrada com o tempo que levou. No rodapé do painel há uma linha de comando. Digite um comando — ou execute chat on e digite uma frase para que um agente de codificação responda.

Clique na barra e todos os comandos são listados com o que fazem. Continue digitando para filtrar, role para o resto, clique em um para preenchê-lo.

Com chat on, prompts iniciam um agente real — qualquer um que você tenha no PATH: Claude Code, Codex, opencode, Gemini, Cursor, Amp, Qwen Code, Factory Droid, goose, Copilot CLI, Aider, Crush, DeepSeek Harness. Ele roda headless, controla o mesmo Studio, e seu trabalho aparece no log. É uma sessão separada do seu terminal, cobrada separadamente, e permitida apenas nas ferramentas rbx-studio. O botão stop ao lado do prompt o cancela.

Oito temas atrás da aba na borda direita. Sua escolha é lembrada.

Por que este

• Push, não poll — 13,6 ms por chamada contra 25,8 ms.
• Edições de script seguras — gravações passam pelo editor de scripts, então trabalho não salvo sobrevive.
• Edições obsoletas são recusadas — devolva o rev de script_read e uma gravação só acontece se ninguém mais tocou no arquivo.
• Nomes de propriedades são verificados contra o motor em execução, então Anchorred volta como uma sugestão, não um erro de runtime.

DeepSeek Harness (dsh)

Este servidor se registra como um plugin dsh. Acrescente esta linha a $DSH_HOME/cordis.patch.yml, ou a $DSH_HOME/profiles/<name>/cordis.patch.yml para apenas um perfil:

- insert:
    - id: mcp-rbx-studio
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: rbx-studio
        transport: stdio
        command: npx
        args: ['-y', '@el4cteo/rbx-studio-mcp']
        cwd: !!js process.cwd()

Depois dsh --profile headless "what is in workspace". Precisa de DEEPSEEK_API_KEY. A mesma linha, comentada, está em config/dsh.cordis.yml para uso com dsh --patch.

Segurança

Apenas loopback. Requisições precisam de um cabeçalho que um navegador não pode definir entre origens e um Host de loopback, então uma página web não pode alcançá-lo, mesmo através de DNS rebinding. A configuração "Allow HTTP Requests" da sua experiência não é tocada.

Desenvolvimento

npm install
npm run build          # TypeScript -> dist/
npm run install:plugin # build the plugin and copy it into Studio
npm test

Precisa de luau, luau-compile e luau-analyze de os lançamentos do Luau em PATH ou em tools/.

Com o Studio aberto e o plugin carregado, node scripts/test-live.mjs verifica o transporte e node scripts/test-live-tools.mjs [--playtest] executa cada ferramenta, node scripts/test-live-sync.mjs verifica sync, e node scripts/test-live-sync-scale.mjs cronometra em 2.000 scripts. Todos se limpam sozinhos.

Licença

MIT.