Cocos MCP 연결 문제 해결: Cursor에 cocos-creator가 표시되지 않음

먼저: 어느 레이어에서 실패했나?

“Cursor가 고장 / 연결 안 됨”이라면 Cursor 쪽 증상부터 보세요: Cursor가 Cocos Creator MCP 연결 후 고장?.

MCP가 무엇을 하는지, “Cocos Creator AI”와 어떻게 다른지 아직 불명확하면 먼저 Cocos Creator MCP란을 읽으세요.

MCP 경로는 네 개의 레이어로 구성됩니다. 어느 레이어에서든 실패하면 “연결할 수 없음”으로 보입니다:

1. 확장 프로그램 설치 및 활성화
        ↓
2. 패널 활성화 (계정 / 라이선스 코드)
        ↓
3. MCP 서버가 실행 중(Running)으로 표시 (localhost)
        ↓
4. AI IDE 구성 작성 및 MCP 목록에 연결됨으로 표시

표시되는 증상	먼저 확인할 것
확장 프로그램 → Cocos MCP Server / MCP Server 메뉴 없음	레이어 1: 패키지 버전, 가져오기 경로, 재시작
패널이 열리지만 시작할 수 없거나 활성화되지 않음	레이어 2: 계정 및 라이선스
시작을 클릭했지만 실행 중이 되지 않음	레이어 3: 포트, 방화벽, 활성화
Creator는 실행 중으로 표시되지만 Cursor에 cocos-creator 없음	레이어 4: 빠른 구성, MCP 재로드, 구성 파일
Cursor에 연결됨으로 표시되지만 씬 노드를 나열할 수 없음	검증 프롬프트, 도구 토글, 올바른 프로젝트 열림

증상 A: 메뉴에 MCP 확장 프로그램이 없음

가능한 원인

1. 2.x / 3.x 패키지 혼용
2. 3.x: 확장 관리자에서 가져오지 않았거나 비활성화 상태
3. 2.x: packages/<플러그인 이름>/ 아래에 있지 않거나, 압축 해제 시 중첩 폴더가 하나 더 있음
4. 2.x: 파일을 넣었지만 Creator를 완전히 재시작하지 않음

해결 방법

Creator 3.x:

1. Cocos MCP 3.x에서 다운로드 — 2.x 팩이 아님
2. 프로젝트 열기 → 확장 프로그램 → 확장 관리자 → 가져오기 → 3.x zip 선택
3. cocos-mcp-server가 활성화되어 있는지 확인하고, 비활성화되어 있으면 활성화
4. 메뉴가 여전히 없으면: Creator를 종료하고 같은 프로젝트를 다시 열기

Creator 2.x:

1. Cocos MCP 2.x에서 다운로드
2. 압축 해제 후 트리 구조가 다음과 같아야 합니다:

프로젝트 루트/
  packages/
    <플러그인 이름>/          ← 플러그인 파일이 여기에 직접 위치
      package.json          ← 이 경로에 있어야 함 (패키지별 이름)

3. 잘못된 중첩 예시:

packages/
  xxx-mcp-unzip/
    <플러그인 이름>/
      package.json

4. 경로를 수정한 후 Creator를 종료하고 재시작합니다 (씬 새로고침만으로는 안 됨). 확장 프로그램 → MCP Server를 확인합니다.

증상 B: 패널이 열리지만 활성화 실패 또는 서비스가 시작되지 않음

가능한 원인

• 계정에 해당 Pro 권한이 없음
• 라이선스 코드 만료 또는 이메일 불일치
• 활성화 전에 시작을 클릭함

해결 방법

1. MCP 패널 열기 (3.x: 확장 프로그램 → Cocos MCP Server → Open Mcp Panel; 2.x: 확장 프로그램 → MCP Server)
2. 다음 중 하나로 활성화:
   • VberAI 계정 + 비밀번호
   • 이메일 + 라이선스 코드
3. 공식 계정 센터에서 플랜/코드를 확인한 후 패널에서 다시 시도
4. 활성화 후에만 MCP Server 설정을 열고 시작을 클릭

활성화하지 않으면 서버가 일반적으로 실행 중 상태에 도달하지 않습니다. Cursor를 탓하기 전에 에디터 측을 먼저 수정하세요.

증상 C: 시작을 클릭했지만 실행 중이 되지 않음

가능한 원인

1. 아직 활성화되지 않음 (증상 B 참조)
2. 포트 사용 중 (3.x는 기본적으로 3000을 사용하는 경우가 많고, 2.x는 패널 설정을 따름)
3. 방화벽/보안 소프트웨어가 localhost 수신을 차단

해결 방법

1. MCP Server 설정 페이지에서 포트를 확인 (아래 예시는 3000을 사용 — 패널 값으로 대체)
2. 이미 수신 중인 프로세스가 있는지 확인:

macOS / Linux:

lsof -iTCP:3000 -sTCP:LISTEN

Windows (PowerShell):

netstat -ano | findstr :3000

3. 다른 프로세스가 포트를 점유 중인 경우:
   • 해당 프로세스를 중지하거나,
   • MCP 패널에서 사용 가능한 포트를 선택한 후 시작을 다시 클릭
4. 방화벽이 127.0.0.1을 허용하는지 확인 (MCP를 공개 인터넷에 노출하지 마세요)
5. 패널에 실행 중이 표시되면 AI IDE를 구성합니다.

증상 D: Creator는 실행 중인데 Cursor에 cocos-creator가 없음

대부분의 “연결 실패” 보고는 여기서 발생합니다: 에디터는 정상, 클라이언트가 구성을 읽지 못함.

해결 방법 (순서대로)

1. Creator에서 MCP 패널이 여전히 실행 중인지 확인 (포트 변경이나 에디터 재시작으로 중지될 수 있음)
2. 도구 관리자를 열고 필요한 도구를 활성화
3. 빠른 구성 열기 → Cursor 선택 → UI에 구성됨이 표시될 때까지 자동 구성
4. Cursor → MCP/도구 목록에서:
   • cocos-creator (또는 패널에 표시된 이름)가 보여야 함
   • 없으면: MCP 다시 로드 (또는 Cursor 재시작) 후 다시 확인
5. 여전히 없으면: Cursor의 MCP 구성에 로컬 브리지 (127.0.0.1 + 패널 포트)가 포함되어 있는지 확인

자동 구성 출력은 Cursor 버전에 따라 다릅니다. 수동으로 확인할 때:

• 서비스 이름이 Cocos MCP와 일치 (예: cocos-creator)
• 호스트가 127.0.0.1 또는 localhost이고, 포트가 Creator와 일치
• 실수로 LAN 또는 공개 IP가 아님

구성을 편집한 후에는 MCP를 다시 로드해야 UI가 이전 상태를 유지하지 않습니다.

다른 AI IDE

빠른 구성에서 Claude Code, Codex, Windsurf, Cline 등을 선택한 후 자동 구성 → 해당 클라이언트에서 MCP 다시 로드를 수행합니다. Cursor를 구성한다고 모든 IDE가 연결되는 것은 아닙니다.

증상 E: 연결됨으로 표시되지만 씬/노드를 나열하거나 편집할 수 없음

가능한 원인

1. Creator에서 열린 프로젝트/씬이 질문한 내용과 일치하지 않음
2. 도구 관리자에서 필요한 도구가 선택 해제됨
3. “디스크의 파일”만 확인했지 에디터 컨텍스트는 확인하지 않음

검증

Cursor에서 읽기 전용 프롬프트를 보냅니다:

Cocos Creator에서 현재 열려 있는 씬의 루트 노드 이름을 나열해 주세요.

결과	의미
계층 구조와 일치	브리지 정상; 다음에 작은 쓰기 시도
명확한 오류 / 도구 없음	증상 C/D로 돌아가기
지어낸 노드 이름	MCP가 사용되지 않을 가능성; 연결 및 도구 토글 확인

그런 다음 작은 쓰기를 시도합니다 (임시 노드를 생성하고 삭제). 큰 편집 전에 커밋하세요.

2.x vs 3.x 빠른 비교표

항목	Creator 3.x	Creator 2.x
제품 페이지	cocos (3.x)	cocos2x
설치	확장 관리자 → 가져오기	프로젝트 packages/에 압축 해제
설치 후	목록에서 활성화	반드시 Creator 재시작
패키지	3.x 전용	2.x 전용
전체 단계	3.x 설치	2.x 설치

패키지를 혼용하면 “메뉴 없음” 또는 “가져오기 실패”로 표시되는 경우가 많습니다 — 이 표를 먼저 사용하세요.

권장 순서 (5분 체크리스트)

순서대로 체크하세요; 대부분의 실패는 처음 네 가지에 있습니다:

1. Creator 주 버전이 MCP zip과 일치 (2.x ↔ 2.x, 3.x ↔ 3.x)
2. 확장 프로그램 활성화 / packages 경로 정확; 2.x는 재시작
3. 패널 활성화 성공
4. 패널에 실행 중 표시; 포트 사용 가능
5. 현재 IDE에 대해 빠른 구성 → 자동 구성
6. AI IDE에서 MCP 다시 로드; cocos-creator 목록에 표시
7. 읽기 전용 프롬프트가 현재 열려 있는 씬의 루트를 나열

그래도 실패하면, 이 정보를 수집하세요

지원팀이나 동료에게 문의할 때 다음을 포함하세요:

• 정확한 Creator 버전 (예: 3.8.x / 2.4.x)
• MCP 팩 유형 (2.x 또는 3.x Pro)
• 패널이 실행 중인지 여부와 포트
• AI IDE 이름/버전 및 MCP 목록 스크린샷
• 정확한 읽기 전용 프롬프트와 응답

브리지는 localhost에서만 유지하세요; MCP 포트를 공개하지 마세요.

관련 문서

• Cocos Creator 3.x MCP 설치
• Cocos Creator 2.x MCP 설치
• Cocos Creator MCP 비디오 설정
• 엔진 선택 가이드: Godot MCP vs Unity MCP vs Cocos MCP