Roblox Studio MCP
AI 에이전트가 Roblox Studio를 구동하게 하세요: 플레이스(place) 읽기, 스크립트 편집, 지오메트리 구축, 플레이 테스트 실행, 스크린샷 캡처. 총 35개의 도구. MIT.
The Studio MCP panel
설치 (Install)
1. 플러그인 (The plugin)
npx -y @el4cteo/rbx-studio-mcp --install-plugin
또는 Releases에서 StudioMCP.rbxmx 파일을 다운로드하여 Studio 플러그인 폴더에 드롭합니다.
2. 서버 (The server)
claude mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp
<details>
<summary>다른 클라이언트 (Other clients)</summary>
Codex CLI:
codex mcp add roblox-studio -- npx -y @el4cteo/rbx-studio-mcp
Cursor, Claude Desktop, Gemini CLI, Windsurf 등: 설정 파일에 추가합니다:
{
"mcpServers": {
"roblox-studio": {
...
VS Code / Copilot (.vscode/mcp.json)은 `
- 핸들(Handles) (
handles=true)은 경로를 대체하는 세션 참조입니다. 이름 변경이나 이동에도 살아남으며, 삭제되거나 만료된 경우 잘못된 객체를 가리키는 대신 오류를 발생시킵니다.
- **
pick**은 화면 지점(전체 뷰포트 기준으로 정규화된) 아래의 객체를 반환합니다.
- **
watch**는 속성(property), 어트리뷰트(attribute) 및 자식 변경 사항을 1~15초 동안 기록합니다. 반응을 확인하려면 입력을 병렬로 전송하십시오.
- **
collisions**는 파트 하나 또는 모델의 모든 파트가 무엇에 부딪혔는지 보고합니다: 접촉 지점(contact point), 법선 벡터(normal), 충격 속도 및 면적을 가장 강한 순서로 기록합니다. 미끄러짐은 충돌로 계산되지 않습니다. 실행 중인 플레이 테스트가 필요합니다.
- **
uisnap**은 UI를 스냅샷합니다. 편집 후 compareTo="<id>"로 다시 호출하면 추가되거나 제거되었거나 변경된 모든 요소를 속성별로 확인할 수 있습니다.
- **
performance op="microprofile"**는 MicroProfiler 프레임을 캡처하고, 모든 스레드에서 해당 프레임을 채운 엔진 범위(engine scope)를 순위별로 매깁니다. export=true는 MicroProfiler 뷰어가 열 파일로 저장합니다. 첫 사용 시 플러그인으로 전송되는 Roblox의 LibMP (MIT)를 사용합니다.
- **
collision op="cast"**는 margin 및 sizeGradient를 사용하여 레이(rays), 블록, 구체 또는 실제 파트(shape="part")를 스윕합니다.
- 클리핑된
execute_luau 결과는 resultId를 반환합니다. source를 생략하고 페이지를 넘겨도 아무것도 재실행되지 않습니다. 결과는 120초 동안 유지됩니다.
파일 작업 (Work on files)
sync는 스크립트를 폴더로 미러링하여 에이전트가 자체 파일 도구로 코드를 편집하고 Studio를 사용하여 테스트할 수 있게 합니다.
sync op="pull" # Studio -> ./studio
sync op="push" # ./studio -> Studio
sync op="watch" # 양방향, 실시간, op="stop"까지
로조 스타일 레이아웃 및 고급 동기화 기능, 그리고 오픈 클라우드 연동
- Rojo-style layout:
Main.server.luau, .client.luau, .luau; 자식 요소를 가진 스크립트는 init을 포함하는 폴더입니다. luau-lsp용으로 sourcemap.json이 작성됩니다.
- 파일의 이름을 바꾸거나 이동하면 해당 스크립트도 함께 이동하며, 속성과 참조를 유지합니다.
- 양쪽에서 모두 수정되었습니까? 이는 충돌(conflict)이며 어느 쪽도 건드리지 않습니다. Studio 버전은
.rbx-sync/conflicts/에 대기합니다. 파일로 병합하고 다시 동기화하거나, prefer: "studio" / "disk"를 전달하십시오.
- 파일을 삭제하면 스크립트도 삭제됩니다 (Ctrl+Z 한 번). Studio에서 삭제된 스크립트는
.rbx-sync/trash로 전송됩니다.
export는 UI 또는 모든 인스턴스 트리를 .build.json 파일로 작성합니다. 이를 편집하고 build를 실행하면, 스크립트를 유지한 채 재구축됩니다. Studio에서 이루어진 수정 사항은 이 파일로 다시 흐릅니다.watch는 무언가 변경될 때만 작동합니다: 2,000개의 스크립트가 있어도 왕복 약 0.5초가 걸립니다. 충돌은 에이전트의 다음 답변에서 표시됩니다.
Open Cloud
일부 호출은 Studio를 넘어 Roblox 자체에 도달합니다. 모든 기능에 하나의 API 키가 필요하며, 그 외에는 이 키 없이 작동합니다.
| |
|---|
assets op="upload" | 로컬 오디오/이미지/모델/비디오 파일을 전송하여 에셋 ID를 얻습니다. |
| ... | |
Creator Dashboard → Credentials에서 키를 생성하고 원하는 권한(permissions)을 추가합니다: 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. 이벤트 스케줄링에는 universe.event:read 및 :write 권한이 필요합니다.
그런 다음 Studio 패널에서:
cloud key <붙여넣기>
cloud user <사용자 ID>
cloud place <장소 ID>
cloud place가 우주 설정을 완료해 줍니다. 입력된 키는 로그와 기록에서 마스킹되며, ~/.rbx-studio-mcp/credentials.json (모드 0600)에 저장됩니다. 플레이스 파일이나 대화 내용에는 절대 남지 않습니다. cloud를 사용하면 설정된 내용을 보여주고, cloud test로 재확인하며, cloud forget으로 삭제합니다. 환경 변수에 있는 ROBLOX_API_KEY 등도 작동하며 우선순위를 가집니다.
주의할 점 두 가지가 있습니다: 플레이테스트는 두 번째 세션을 연결하므로, studioId를 전달하고 영구적으로 유지되어야 하는 변경 사항에는 '편집(edit)' 기능을 사용해야 합니다. 또한, device 에뮬레이션은 device op="stop"이 될 때까지 계속 활성화됩니다.
콘솔 패널 (The console panel)
모든 호출은 소요 시간이 기록됩니다. 패널 하단에는 명령줄이 있습니다. 명령어를 입력하거나, chat on을 실행하고 문장을 입력하여 코딩 에이전트의 답변을 받을 수 있습니다.
| |
|---|
help | 모든 목록 보기 (list everything) |
| ... | |
| 클릭하면 모든 명령어와 그 기능이 나열됩니다. 계속 타이핑하여 필터링하고, 스크롤하여 나머지를 확인하며, 하나를 클릭하여 내용을 채울 수 있습니다. 엔터를 누르거나 보내기(send) 버튼을 클릭하세요. | |
chat on을 사용하면 프롬프트가 실제 에이전트를 시작합니다. 이 에이전트는 PATH에 설정된 31개의 지원되는 에이전트 중 하나를 사용합니다: Claude Code, Codex, opencode, Gemini, Cursor, Amp, Qwen Code, Factory Droid, goose, Copilot CLI, Aider, Crush, DeepSeek Harness, Kimi Code, Cline, Kilo Code, Auggie, Qoder, Continue, Kiro, Mistral Vibe, Grok CLI, OpenHands, Hermes, OpenClaw, Warp Oz, Rovo Dev, Forge, pi, Letta Code 또는 Trae Agent. 이는 헤드리스(headless)로 실행되며, 동일한 스튜디오를 구동하고, 그 작업 내용은 프롬프트 아래 로그에 나타납니다. 터미널과는 별도의 세션이며 개별적으로 청구됩니다. Claude Code와 Copilot은 rbx-studio 도구로 제한되며, 나머지 에이전트들은 자체 권한 설정을 사용합니다. 프롬프트 옆의 정지(stop) 버튼을 누르면 실행이 취소됩니다.
여덟 가지 테마가 있습니다: 헤더의 점들 중 하나를 선택하거나, theme <이름>을 사용하여 설정할 수 있습니다. 선택한 내용은 기억됩니다. 이번 달 특별 기능은 Hyperline입니다: 밴드가 라이브 터널이 되어 모든 호출이 빛의 흔적으로 나타납니다.
왜 이것인가 (Why this one)
- 폴링(poll) 대신 푸시(push) — 호출당 13.6ms로, 기존 25.8ms 대비 개선되었습니다.
- 안전한 스크립트 편집 — 쓰기 작업이 스크립트 에디터를 거치므로 저장하지 않은 작업도 유지됩니다.
- 오래된 편집은 거부됨 — 라인 범위 및 전체 파일 편집에는
script_read의 rev가 필요하며, 다른 사람이 파일을 건드리지 않았을 경우에만 적용됩니다.
- 속성 이름 확인 — 속성 이름은 실행 중인 엔진과 비교하여 확인되므로,
Anchorred는 런타임 오류가 아닌 제안으로 표시됩니다.
DeepSeek Harness (dsh)
이 서버는 dsh 플러그인으로 등록됩니다. 다음 행을 $DSH_HOME/cordis.patch.yml 또는 단일 프로필에 대해서만 $DSH_HOME/profiles/<name>/cordis.patch.yml에 추가하십시오:
- insert:
- id: mcp-rbx-studio
name: '@deepseek-ai/dsh-mcp-client'
...
그런 다음 dsh --profile headless "what is in workspace"를 실행해야 합니다. DEEPSEEK_API_KEY가 필요합니다.
동일한 행을 주석 처리하여 config/dsh.cordis.yml에 넣어 dsh --patch와 함께 사용할 수 있습니다.
보안(Security)
루프백(Loopback) 전용입니다. 요청에는 브라우저가 크로스-오리진(cross-origin)으로 설정할 수 없는 헤더와 루프백 Host가 필요하므로, DNS 리바인딩을 통해서도 웹 페이지가 접근할 수 없습니다. 사용자의 경험(experience)의 "HTTP 요청 허용(Allow HTTP Requests)" 설정은 변경되지 않습니다.
개발(Development)
npm install
npm run build
npm run install:plugin
...
luau, luau-compile, 그리고 luau-analyze가 PATH 또는 tools/에 Luau 릴리스(the Luau releases)를 통해 필요합니다.
Studio를 열고 플러그인을 로드한 상태에서, node scripts/test-live.mjs는 전송 계층을 확인하고, node scripts/test-live-tools.mjs [--playtest]는 모든 도구를 실행하며, node scripts/test-live-sync.mjs는 동기화(sync)를 확인하고, node scripts/test-live-sync-scale.mjs는 2,000개의 스크립트에 대해 시간을 측정합니다. 모두 자체적으로 정리됩니다.
라이선스(Licence)
MIT.
