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 (Edit)을 지정해야 합니다.
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 (Edit, Client 또는 Server)을 지정해야 합니다.
플레이테스트
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 docs, 클라우드 API, 성능 최적화 가이드)에서 콘텐츠를 가져옵니다. 가져온 콘텐츠 내에서 키워드 검색을 지원합니다.
skill	디버깅, 장치 시뮬레이션 및 문서 검색과 같은 특정 기술에 대한 자세한 지식, 모범 사례 또는 참조 자료를 가져옵니다.
세션 관리
list_roblox_studios	모든 연결된 Studio 인스턴스를 나열하며, 이름, ID 및 활성 상태를 포함합니다. 여러 Studio 창이 열려 있을 때 유용합니다.
set_active_studio	Studio 인스턴스를 활성으로 설정하여 모든 후속 도구 호출이 해당 인스턴스를 대상으로 하도록 합니다.

Studio에서 MCP 서버 활성화

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

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

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

클라이언트 연결하기

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

클라이언트가 지원되는 경우 빠른 연결을 사용하십시오.
그렇지 않은 경우 클라이언트가 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 구문을 확인하십시오. 쉼표나 괄호가 누락된 경우 구성이 로드되지 않을 수 있습니다.