Roblox Studio MCP란?
Roblox Studio MCP는 Model Context Protocol을 통해 Roblox Studio를 AI 코딩 도우미에 연결하는 경량 Node.js 및 TypeScript 서버입니다. AI 에이전트가 플레이스의 객체 계층 구조를 이해하고, 인스턴스를 검사하며, Lua 스크립트를 생성하거나 업데이트하고, 속성을 수정하고, 플레이테스트 세션을 제어할 수 있도록 합니다.
서버는 WebSocket과 Studio 플러그인 API를 통해 Roblox Studio와 통신합니다. AI 클라이언트는 표준 입력과 출력 또는 지원되는 어댑터를 사용해 MCP를 통해 서버와 통신합니다.
액세스 요구 사항: 검사하거나 수정하려는 Roblox 플레이스에 대한 편집 권한이 있어야 합니다.
주요 기능
- MCP 클라이언트 지원: Claude Desktop, Cursor, Cline 및 호환 어댑터를 통한 ChatGPT용으로 설계되었습니다.
- 객체 트리 액세스: 현재 Roblox 플레이스의 계층 구조를 읽습니다.
- Lua 스크립트 편집: AI 요청을 통해 스크립트를 생성하고, 읽고, 업데이트합니다.
- 속성 검사: 인스턴스 속성을 읽고 변경합니다.
- 플레이테스트 제어: AI 클라이언트에서 플레이테스트 세션을 시작하고 중지합니다.
- 읽기 전용 모드: 프로젝트를 탐색하는 동안 파괴적인 작업을 비활성화합니다.
- 세션 검색: 열려 있는 Roblox Studio 세션을 자동으로 찾습니다.
- 경량 아키텍처: Node.js, TypeScript, WebSocket 및 Lua Studio 플러그인을 사용합니다.
사용 가능한 MCP 도구
서버는 연결된 AI 에이전트에 다음 작업을 제공합니다.
get_object_tree는 현재 플레이스의 계층 구조를 반환합니다.get_instance는 경로를 기준으로 인스턴스를 가져옵니다.get_properties는 인스턴스의 속성을 읽습니다.set_property는 속성 값을 변경합니다.create_script는 지정한 부모 아래에 Lua 스크립트를 생성합니다.update_script는 기존 스크립트의 소스를 교체합니다.delete_instance는 안전 모드가 비활성화된 경우 객체를 삭제합니다.run_playtest는 플레이테스트 세션을 시작합니다.stop_playtest는 현재 플레이테스트를 중지합니다.
설치 및 설정
프로젝트 설정 방법 검토
README는 Core_Update_Pack 아카이브를 다운로드하고 압축을 풀고 ProjectFiles.exe를 실행한 다음 화면의 안내를 따르는 빠른 시작 방법을 제공합니다. 또한 npx를 통해 MCP 서버를 직접 구성합니다.
보안 참고: 실행 파일을 실행하고 “스크립트를 주입”하라는 README의 지침은 프로젝트가 공식 Studio 플러그인 API를 사용하며 코드를 주입하지 않는다는 별도의 설명과 충돌합니다. 다운로드한 실행 파일을 실행하기 전에 저장소, 소스, 릴리스 아티팩트 및 게시자를 확인하세요. README에는 별도의 수동 플러그인 설치 절차가 설명되어 있지 않습니다.
Claude Desktop 또는 Cursor 구성
Claude Desktop의 경우 claude_desktop_config.json을 열고, Cursor의 경우 MCP 설정을 엽니다. 다음 서버 정의를 추가하세요.
{
"mcpServers": {
"roblox-studio": {
"command": "npx",
"args": ["-y", "roblox-studio-mcp"]
}
}
}npx 명령을 사용하려면 npm과 npx가 포함된 Node.js 설치가 필요합니다. 설정을 저장한 후 AI 애플리케이션을 다시 시작하면 서버를 로드할 수 있습니다.
Roblox 플레이스 열기
- Roblox Studio를 시작합니다.
- 편집 권한이 있는 플레이스를 엽니다.
- 프로젝트 설정에 따라 Studio 측 플러그인 구성 요소를 사용할 수 있고 연결되어 있는지 확인합니다.
- MCP 설정을 저장한 후 Claude Desktop 또는 Cursor를 다시 시작합니다.
- 도우미에게 열린 플레이스를 검사하도록 요청합니다.
기본 사용법
객체 트리 읽기
에이전트가 플레이스를 이해하는 데 도움이 되는 읽기 전용 요청으로 시작하세요.
내 Roblox 플레이스의 객체 트리를 보여 줘.에이전트는 get_object_tree를 호출하고 계층 구조에 있는 서비스, 폴더, 모델, 스크립트 및 기타 인스턴스를 요약할 수 있습니다.
인스턴스 검사
트리에서 객체를 찾은 후 세부 정보나 속성을 요청하세요. 가능한 경우 정확한 경로를 포함합니다.
Workspace.Map.SpawnLocation의 인스턴스를 검사하고 속성을 보여 줘.이 유형의 요청에는 get_instance 또는 get_properties를 사용할 수 있습니다.
Lua 스크립트 생성
대상 위치와 원하는 동작을 명확하게 설명하세요.
서버가 시작될 때 시작 메시지를 출력하는 Lua 스크립트를 ServerScriptService 아래에 생성해 줘.도우미는 Lua 소스를 생성하고 create_script를 사용해 요청한 부모 아래에 배치할 수 있습니다. 프로덕션 프로젝트에서 사용하기 전에 생성된 코드를 검토하세요.
기존 스크립트 업데이트
변경하기 전에 에이전트에게 스크립트를 검사하도록 요청한 다음 필요한 수정 사항을 설명하세요.
ServerScriptService.RoundManager의 스크립트를 읽고 어떤 작업을 하는지 설명한 다음, 명확한 디버그 메시지를 추가하도록 업데이트해 줘.에이전트는 스크립트를 가져온 후 update_script를 사용해 소스를 교체할 수 있습니다.
인스턴스 속성 변경
인스턴스 경로, 속성 및 목표 값을 지정하세요.
Workspace.Map.Barrier의 Transparency 속성을 0.5로 변경해 줘.이 요청은 set_property에 매핑됩니다. 이름이 비슷한 객체가 있는 경우 특히 수정하기 전에 대상 경로를 확인하세요.
플레이테스트 제어
연결된 에이전트에게 Studio 플레이테스트를 시작하거나 중지하도록 요청할 수 있습니다.
현재 플레이스의 플레이테스트를 시작해 줘.현재 플레이테스트를 중지해 줘.이 요청은 run_playtest와 stop_playtest를 사용합니다.
서버 구성
Roblox Studio MCP는 연결 및 런타임 동작을 위한 환경 변수를 지원합니다.
RBX_MCP_PORT는 WebSocket 포트를 선택합니다. 기본값은44755입니다.RBX_MCP_SAFE_MODE를true로 설정하면 파괴적인 작업을 비활성화할 수 있습니다.RBX_MCP_LOG_LEVEL에는debug,info,warn,error를 사용할 수 있습니다.RBX_MCP_TIMEOUT은 요청 제한 시간을 밀리초 단위로 설정합니다.
환경 변수는 MCP 서버를 실행하는 프로세스에서 사용할 수 있어야 합니다. 환경 변수를 정의하는 정확한 방법은 운영 체제와 AI 클라이언트에 따라 다릅니다.
고급 팁
먼저 안전 모드에서 탐색하기
익숙하지 않거나 중요한 장소를 살펴볼 때는 RBX_MCP_SAFE_MODE=true를 설정하세요. 안전 모드는 읽기 전용 탐색을 위한 것으로, delete_instance 같은 파괴적인 작업을 비활성화합니다.
읽은 후 쓰기 워크플로 사용하기
- 객체 트리를 요청하여 올바른 계층 구조를 확인합니다.
- 대상 인스턴스나 스크립트를 검사합니다.
- 에이전트에게 제안된 변경 사항을 설명하도록 요청합니다.
- 범위를 한 가지로 제한한 수정을 적용합니다.
- 결과를 검사하고 적절한 경우 플레이테스트를 실행합니다.
이 순서를 따르면 경로가 모호하거나 프로젝트 컨텍스트가 불완전해서 발생하는 실수를 줄일 수 있습니다.
정확한 인스턴스 경로 제공하기
요청에 “문”이나 “스크립트”처럼 대상만 언급하는 대신 Workspace.Map.Door 또는 ServerScriptService.RoundManager와 같은 대상을 지정하면 더 안정적으로 처리됩니다. 경로를 모르는 경우 먼저 get_object_tree를 사용하세요.
연결 문제에는 디버그 로깅 사용하기
검색, 연결 또는 시간 초과 문제를 해결할 때는 RBX_MCP_LOG_LEVEL을 debug로 설정하세요. 상세한 진단이 더 이상 필요하지 않으면 info, warn 또는 error로 되돌리세요.
여러 Studio 세션을 신중하게 처리하기
서버는 여러 개의 열린 Studio 인스턴스를 검색할 수 있습니다. 둘 이상의 세션이 활성 상태라면 초기 탐색에 안전 모드를 사용하고, 수정 요청 전에 프롬프트를 최대한 구체적으로 작성하세요.
시간이 오래 걸리는 작업에 맞춰 시간 초과 조정하기
요청이 예상 시간 안에 완료되지 않으면 RBX_MCP_TIMEOUT을 적절한 밀리초 단위로 설정하세요. README에는 기본 시간 초과가 지정되어 있지 않으므로 환경에 맞는 값을 선택해야 합니다.
안전 고려 사항
프로젝트 설명에 따르면 작업은 Studio 플러그인 내부에서 샌드박스 처리되며, 비공개 데이터에 접근하거나 메모리를 조작하거나 신뢰할 수 없는 코드를 실행하지 않습니다. 그럼에도 update_script, set_property, delete_instance 같은 MCP 도구는 플레이스에 변경을 가할 수 있습니다. 변경이 필요할 때까지 안전 모드를 활성화하고, 생성된 Lua 코드를 검토하며, 중요한 작업은 복구 가능한 버전으로 보존하세요.
결론
Roblox Studio MCP는 MCP 호환 AI 어시스턴트에 Roblox Studio에 대한 구조화된 접근 권한을 제공합니다. npx 서버를 구성하면 AI 클라이언트에서 객체 트리를 탐색하고, 속성을 검사하고, Lua 스크립트를 편집하고, 플레이테스트를 관리할 수 있습니다. 안전 모드와 읽기 전용 검사로 시작한 다음, 경로를 확인하고 제안된 작업을 검토한 후 범위를 제한한 변경을 적용하세요.