연결, 권한, Sync, 검증 문제를 단계별로 좁혀 가는 가이드입니다.
플러그인이 연결되지 않을 때
증상: “Connection failed” 또는 Roblox Studio에서 플러그인이 연결 안 됨으로 표시됩니다.
- MCP 서버가 실행 중인지 확인:
npx -y @weppy/roblox-mcp - Roblox Studio: Plugins 탭 → WEPPY → Connect 클릭
localhost:3002를 차단하는 방화벽, 바이러스 백신, VPN이 없는지 확인- Roblox Studio와 MCP 서버를 모두 재시작
AI 클라이언트가 MCP 서버를 인식하지 못할 때
- AI 클라이언트 설정에서 올바른 명령어가 사용되는지 확인:
npx -y @weppy/roblox-mcp - Node.js 18 이상이 설치되어 있는지 확인:
node --version - Windows에서 권한 오류가 발생하면 터미널을 관리자 권한으로 실행해보세요
- 사용 중인 AI 앱의 설치 가이드를 확인하세요
”Pro feature required” 안내
Basic에서 Pro 전용 액션을 요청하면, 가능한 경우 우회 방법을 찾아 처리합니다. 다만 우회 흐름이 추가 토큰을 소모하고 항상 같은 결과를 보장하지는 않습니다.
또한 우회 자체가 불가능한 일부 Pro 전용 도구는 Basic에서 실행할 수 없습니다. 이 안내가 반복적으로 나타난다면 Pro 전환을 고려해보세요.
Sync가 동작하지 않을 때
- Sync 상태 확인: AI에게
manage_sync status요청 - Sync 시작 전에 플러그인이 연결되어 있는지 확인
- Reverse sync(파일 → Studio)가 안 되면 Pro 티어 활성화 여부 확인
- 로컬 sync 폴더가 존재하고 쓰기 권한이 있는지 확인
자세한 Sync 설정은 양방향 Sync를 참고하세요.
호환 AI 클라이언트
| 클라이언트 | Basic | Pro |
|---|---|---|
| Claude Code | ✅ | ✅ |
| Claude Desktop | ✅ | ✅ |
| Cursor | ✅ | ✅ |
| Codex CLI | ✅ | ✅ |
| Codex Desktop | ✅ | ✅ |
| Gemini CLI | ✅ | ✅ |
| MCP 지원 앱 | ✅ | ✅ |
서버 명령어: npx -y @weppy/roblox-mcp
시스템 요구 사항
| 항목 | 최솟값 |
|---|---|
| Node.js | 18.0.0 이상 |
| Roblox Studio | 최신 버전 (자동 업데이트 유지) |
| 운영 체제 | Windows 10+ 또는 macOS 12+ |
| 네트워크 | localhost:3002 접근 가능해야 함 |
Basic vs Pro 기능 비교
Basic (무료) 도 AI 코딩 작업의 핵심 흐름 대부분을 그대로 사용할 수 있습니다. 인스턴스·속성·스크립트·선택·카메라·로그를 다루는 핵심 도구가 모두 포함되고, Studio → Local 단방향 Sync 와 도구 실행 기록도 그대로 사용 가능합니다. Pro 는 양방향 Sync, 대량 작업, 그리고 지형·조명·물리·오디오·애니메이션 같은 고급 도구 묶음을 추가합니다.
| 기능 | Basic | Pro |
|---|---|---|
| 인스턴스 검색·생성·삭제·복제·이동 | ✅ | ✅ |
| 인스턴스 트리·계층 탐색 | ✅ | ✅ |
| 속성·태그 읽기·쓰기 | ✅ | ✅ |
| 스크립트 읽기·작성·수정 | ✅ | ✅ |
| 선택 관리 | ✅ | ✅ |
| 카메라 이동·포커스 | ✅ | ✅ |
| 로그 조회 | ✅ | ✅ |
| 시스템 정보·연결 확인 | ✅ | ✅ |
| 도구 실행 기록·통계 | ✅ | ✅ |
| Studio → Local 단방향 Sync | ✅ | ✅ |
| 양방향 Sync (Local → Studio) | — | ✅ |
| 타입별 Direction / Apply Mode | — | ✅ |
| Sync 변경 히스토리 | — | ✅ |
| 멀티 Place 동기화 (최대 3개) | — | ✅ |
| 대량 작업 (일괄 생성·수정) | — | ✅ |
| 조명·대기권 제어 | — | ✅ |
| 지형 생성·편집 | — | ✅ |
| 트윈·애니메이션 제어 | — | ✅ |
| 오디오 제어 | — | ✅ |
| 파티클·이펙트 | — | ✅ |
| 물리 그룹·콜리전 | — | ✅ |
| 공간 쿼리·레이캐스트 | — | ✅ |
| 에셋 검색·삽입·익스포트 | — | ✅ |
| 스크린샷 캡처 | — | ✅ |
| Playtest 자동 실행·테스트 주입 | — | ✅ |
| 배치 실행·임의 Luau 코드 | — | ✅ |
Basic 에서 Pro 전용 기능을 요청하면 가능한 범위에서 우회 처리하지만, 토큰 소모가 늘어나고 일부 기능은 우회가 불가능합니다. 자세한 내용은 위의 “Pro feature required” 안내 항목을 참고하세요.
자주 발생하는 오류 메시지
| 오류 | 원인 | 해결 방법 |
|---|---|---|
ECONNREFUSED localhost:3002 | MCP 서버 미실행 | npx -y @weppy/roblox-mcp 실행 |
Timeout waiting for plugin | Studio 플러그인 미연결 | 플러그인 패널에서 Connect 클릭 |
Forbidden path | CoreGui/CorePackages 접근 시도 | 유효한 인스턴스 경로만 사용 |
Place ID mismatch | 잘못된 Place 연결됨 | 올바른 Studio 세션에서 재연결 |
도움이 필요하면
여전히 문제가 해결되지 않으면 GitHub Discussions에 다음 정보를 포함해 문의하세요:
- 운영 체제 및 Node.js 버전
- AI 클라이언트 및 버전
- 오류 메시지 또는 로그
- 이미 시도한 단계