Roblox Studio MCP 서버에 연결하기 | 설명서

Roblox Studio MCP 서버는 Roblox Studio에 내장되어 있습니다. 이는 AI 도구가 외부 애플리케이션과 안전하게 통신할 수 있도록 해주는 개방형 표준인 모델 컨텍스트 프로토콜(MCP)를 구현합니다. 연결되면 AI 클라이언트는 열린 Studio 세션과 직접 상호작용할 수 있으며, 데이터 모델을 탐색하고, 스크립트를 작성하고, Luau 코드를 실행하고, 플레이 모드에서 게임을 테스트할 수 있습니다.

이 가이드는 Studio MCP 서버를 인기 있는 AI 클라이언트에 연결하는 방법을 보여줍니다. 설정은 클라이언트에 따라 다르지만, 기본 아이디어는 동일합니다: 클라이언트를 MCP 서버에 연결하도록 구성한 다음, 클라이언트에서 활성 Studio 세션으로 명령을 전송합니다.

전제 조건

서버에 연결하기 전에 최신 버전의 Roblox Studio와 선호하는 MCP 클라이언트가 컴퓨터에 설치되어 있는지 확인하세요.

Studio MCP 서버 작동 방식

서버는 귀하의 머신에서 로컬 프로세스로 실행되며, stdio 전송을 사용하여 AI 클라이언트와 통신합니다. 모든 작업은 AI 클라이언트를 통해 시작되며, 이후 이 채널을 통해 요청을 전송하여 Studio 세션 내에서 작업을 수행합니다.

서버는 다음과 같은 도구를 제공합니다:

스크립트
script_read	점 표기법 경로(예: game.ServerScriptService.MyScript)를 사용하여 게임에서 스크립트를 읽습니다. 전체 스크립트 또는 특정 줄 범위를 읽는 것을 지원합니다.
multi_edit	하나의 작업으로 스크립트에 여러 편집을 적용합니다. 대상 경로가 존재하지 않으면 새 스크립트를 생성합니다. datamodel_type(편집)을 지정해야 합니다.
script_search	모호한 일치를 사용하여 이름으로 스크립트를 검색합니다. 최대 10개의 결과를 반환합니다.
script_grep	게임의 모든 스크립트에서 문자열 패턴을 검색합니다. 최대 50개의 일치를 반환합니다.
자산 및 콘텐츠 생성
generate_mesh	AI를 사용하여 텍스처가 있는 3D 메시를 텍스트 프롬프트에서 생성합니다.
generate_material	사용자 정의 재료 변형을 생성합니다. 부품에 적용할 기본 재료 및 재료 변형 이름을 반환합니다.
generate_procedural_model	프리미티브 부품(블록, 구, 실린더, 쐐기)으로 구성된 3D 객체를 구성 가능한 속성을 가진 ProceduralModel로 생성합니다. 참조 이미지 및 사용자 정의 부품 스키마를 지원합니다.
wait_job_finished	절차적 모델 생성 작업이 완료될 때까지 기다리고 최종 상태를 반환합니다.
search_asset	Creator Store(공개 마켓플레이스) 및 Creator Inventory(사용자, 그룹 또는 유니버스)에서 자산을 검색합니다. 자산 유형, 가격, 태그 및 범위로 필터링을 지원합니다.
insert_asset	숫자 Roblox 자산 ID로 게임에 자산을 삽입합니다. 모델, 메시, 이미지, 오디오, 비디오, 애니메이션 및 패키지를 지원합니다.
upload_image	HTTP URL에서 이미지 배치를 Roblox 자산 서버에 업로드하고 이미지 경로를 자산 ID 맵으로 반환합니다.
store_image	로컬 파일 경로에서 이미지를 로드하고 다른 도구에 전달할 수 있는 이미지 URI를 반환합니다(예: generate_procedural_model의 참조 이미지로 사용).
데이터 모델 탐색
subagent	복잡한 다단계 작업을 자율적으로 처리하기 위해 전문화된 서브 에이전트를 시작합니다. 사용 가능한 유형에는 explore(코드베이스 조사 및 게임 상태 쿼리용)와 playtest(게임 플레이 시나리오 실행 및 결과 검증용)가 포함됩니다.
search_game_tree	인스턴스 계층 구조를 평면 JSON 배열로 탐색합니다. 경로, 인스턴스 유형 및 키워드로 필터링을 지원하며, 깊이 제한을 구성할 수 있습니다.
inspect_instance	특정 인스턴스에 대한 자세한 정보를 반환하며, 모든 읽을 수 있는 속성, 사용자 정의 속성 및 자식 및 후손의 요약을 포함합니다.
Luau 실행
execute_luau	Studio에서 Luau 코드를 실행합니다. 결과 또는 오류를 반환합니다. datamodel_type(편집, 클라이언트 또는 서버)을 지정해야 합니다.
플레이 테스트
get_studio_state	플레이 상태 및 사용 가능한 데이터 모델 유형을 포함하여 Studio의 현재 상태를 가져옵니다.
start_stop_play	플레이 테스트를 시작하거나 중지합니다.
get_console_output	Studio 출력 로그에서 출력을 검색합니다.
screen_capture	현재 Studio 뷰포트를 캡처하고 이미지 데이터를 반환합니다. 선택적으로 사용자 정의 카메라 위치 및 주시 대상을 수용합니다.
플레이어 입력 시뮬레이션
character_navigation	플레이어 캐릭터를 주어진 위치 또는 인스턴스 경로로 이동합니다. 구성 가능한 속도 배율을 지원합니다.
user_keyboard_input	키 다운, 키 업, 키 누르기, 텍스트 입력 또는 대기와 같은 하나 이상의 키보드 작업을 순서대로 전송합니다. 특정 UI 인스턴스를 타겟팅할 수 있습니다.
user_mouse_input	이동, 클릭, 버튼 다운/업, 스크롤 또는 대기와 같은 하나 이상의 마우스 작업을 순서대로 전송합니다. 특정 인스턴스 또는 화면 좌표를 타겟팅할 수 있습니다.
문서 및 기술
http_get	허용된 Roblox 문서 URL(엔진 API 참조, Creator 문서, 클라우드 API, 성능 최적화 가이드)에서 콘텐츠를 가져옵니다. 가져온 콘텐츠 내에서 키워드 검색을 지원합니다.
skill	디버깅, 장치 시뮬레이션 및 문서 검색과 같은 특정 기술에 대한 자세한 지식, 모범 사례 또는 참조 자료를 검색합니다.
세션 관리
list_roblox_studios	연결된 모든 Studio 인스턴스를 나열하며, 이름, ID 및 활성 상태를 포함합니다. 여러 Studio 창이 열려 있을 때 유용합니다.
set_active_studio	Studio 인스턴스를 활성으로 설정하여 이후의 모든 도구 호출이 해당 인스턴스를 대상으로 하도록 합니다.

Studio에서 MCP 서버 활성화

Studio에서 MCP 서버를 활성화하려면:

Assistant를 엽니다.
… ⟩ MCP 서버 관리를 클릭합니다.
Studio를 MCP 서버로 활성화를 켭니다.

활성화되면 설정 패널에 빠른 연결 옵션과 다양한 클라이언트에 대한 설정 지침이 표시됩니다. 클라이언트가 성공적으로 연결되면 연결된 클라이언트 수를 나타내는 녹색 표시기가 나타납니다.

클라이언트 연결

클라이언트를 빠른 연결, JSON 구성 또는 CLI 명령을 사용하여 Studio MCP 서버에 연결할 수 있습니다.

클라이언트가 지원되는 경우 빠른 연결을 사용하세요.
그렇지 않은 경우 클라이언트가 MCP 구성 파일을 지원하는 경우 JSON 구성을 사용하세요.
그렇지 않으면 CLI 명령을 사용하세요.

Studio MCP 서버는 stdio 전송을 지원하는 모든 클라이언트와 함께 작동합니다. 구성을 추가한 후 클라이언트의 문서를 따라 설정을 완료하고, 변경 사항을 적용하기 위해 클라이언트를 다시 시작하세요.

MCP 클라이언트는 열린 Roblox 장소의 콘텐츠를 읽고 수정할 수 있습니다. 신뢰할 수 있는 클라이언트만 연결하세요.

빠른 연결

빠른 연결은 다음 클라이언트를 지원합니다:

Antigravity
Codex CLI
Claude Code
Claude Desktop
Cursor
Gemini CLI
Visual Studio Code

빠른 연결을 사용하여 연결하려면:

Assistant 설정 ⟩ MCP 서버로 이동합니다.
빠른 연결 드롭다운을 확장하여 컴퓨터에 설치된 지원 클라이언트를 봅니다.
선택한 클라이언트를 켭니다.

원하는 클라이언트가 빠른 연결 목록에 나타나지 않으면 설치하고 Roblox Studio를 다시 시작하세요.

JSON 구성

대부분의 MCP 클라이언트는 JSON 구성 파일을 지원합니다. 다음 예제는 사용할 수 있는 완전한 구성을 보여줍니다.

Roblox Studio가 유일한 MCP 서버인 경우 이러한 구성을 그대로 사용하세요. 여러 MCP 서버를 사용하는 경우 Roblox_Studio 항목을 복사하여 기존 mcpServers 사전에 추가하세요.

당신의 mcp.json 파일에는 이미 다른 항목이 포함되어 있을 수 있습니다. Roblox_Studio 구성을 추가할 때는 각 항목이 쉼표로 구분되어 있는지 확인하세요. 누락된 쉼표는 잘못된 JSON을 초래하고 구성이 로드되지 않게 합니다.

구성은 운영 체제에 따라 다릅니다:

Windows

{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "%LOCALAPPDATA%\\Roblox\\mcp.bat"
      ]
    }
  }
}

macOS

{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP"
    }
  }
}

CLI 명령

일부 MCP 클라이언트는 JSON 구성 대신 CLI 명령이 필요합니다. 운영 체제에 맞는 적절한 명령을 사용하세요:

Windows

cmd.exe /c %LOCALAPPDATA%\Roblox\mcp.bat

macOS

/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP

여러 Studio 인스턴스 사용

하나의 MCP 클라이언트를 여러 개의 실행 중인 Studio 인스턴스에 동시에 연결할 수 있습니다. 서버는 컨텍스트에 따라 사용할 인스턴스를 자동으로 결정합니다(예: 특정 게임이나 해당 인스턴스에만 존재하는 객체를 참조하는 경우).

list_roblox_studios 및 set_active_studio를 사용하여 수동으로 인스턴스를 전환할 수 있습니다.

연결 확인

클라이언트를 설정한 후 Roblox Studio에서 연결이 작동하는지 확인하세요:

Assistant를 엽니다.
… ⟩ MCP 서버 관리를 클릭합니다.
Studio를 MCP 서버로 활성화 아래에서 클라이언트가 성공적으로 연결되었음을 확인하기 위해 녹색 표시기를 확인합니다.

문제 해결

서버가 표시되지 않거나 도구를 사용할 수 없는 경우:

Roblox Studio와 MCP 클라이언트를 모두 다시 시작하세요.
명령 또는 바이너리 경로가 올바르고 파일이 존재하는지 확인하세요.
JSON 구문을 확인하세요. 누락된 쉼표나 괄호도 구성이 로드되지 않게 할 수 있습니다.