Minecraft MCP 통합

Minecraft용 모델 컨텍스트 프로토콜(MCP) 통합으로 AI 어시스턴트가 Minecraft 서버와 상호 작용할 수 있습니다. 이 통합을 통해 AI 모델은 봇을 통해 Minecraft 세계를 관찰하고 상호 작용할 수 있습니다.

필수 조건

1. 마인크래프트 런처
2. Node.js 18 이상
3. 클로드 데스크톱 앱
4. Java 21.0.5(권장)

⚠️ 참고: 현재 macOS/Linux에서만 테스트되었습니다. Windows 호환성은 보장되지 않습니다.

중요 참고 사항

1. F3+P 단축키 사용 : F3+P를 함께 누르세요. "포커스를 잃었을 때 일시 정지" 기능이 켜지고 꺼집니다. 이 기능을 끄면 Claude 데스크톱으로 전환할 수 있으며, Minecraft는 일시 정지 없이 계속 실행됩니다.

2. Claude 재시작 시 연결 문제 : Minecraft 서버 실행 중 Claude를 재시작하면 Java 프로세스 지연으로 인해 다음 Claude 실행 시 MCP 연결 문제가 발생할 수 있습니다. 해결 방법은 문제 해결: MCP 연결 실패를 참조하세요.

설치 단계

1. Minecraft 서버 다운로드 및 설정
   • mcversions.net/1.21 에서 Minecraft 서버 v1.21을 다운로드하세요
   • Java 21.0.5가 아직 설치되어 있지 않으면 설치하세요(다른 버전은 테스트되지 않음)
   • 전용 디렉토리를 만듭니다(예: ~/minecraft-server/ )
   • 다운로드한 server.jar 파일을 이 디렉토리에 넣으세요.
   • server.jar 파일의 절대 경로를 적어 두세요.
2. MCP 통합 설치 및 구성빠른 설치(권장):지엑스피1CLI 프롬프트에 따라 설정을 완료하세요.또는 수동 설정:
   • ~/Library/Application Support/Claude/claude_desktop_config.json 으로 이동합니다.
   • MCP 서버 구성을 추가합니다.
   { "mcpServers": { "mcp-minecraft": { "command": "npx", "args": [ "-y", "mcp-minecraft@latest", "--server-jar", "/absolute/path/to/minecraft-server/server.jar" ] } } }

   ⚠️ /absolute/path/to/minecraft-server/server.jar 실제 server.jar 경로로 바꾸세요.

3. Claude Desktop 실행
   • 구성을 완료한 후 Claude Desktop을 시작합니다.
4. 서버에 연결
   • Minecraft 런처 열기
   • Minecraft Java Edition v1.21을 설치하고 실행하세요
   • "재생"을 클릭하고 "멀티플레이어"를 선택하세요
   • "서버 추가"를 클릭하세요
   • 서버 세부 정보를 입력하세요:
     • 서버 이름: Minecraft Server
     • 서버 주소: localhost:25565
   • "완료"를 클릭하세요

특징

자원

통합을 통해 다음 MCP 리소스가 노출됩니다.

• minecraft://bot/location - 세계에서 현재 봇의 위치
• minecraft://bot/status - 봇 연결 상태

도구

사용 가능한 MCP 도구:

• chat - 서버에 채팅 메시지 보내기
• jump - 봇을 점프하게 만듭니다
• moveForward - 봇을 앞으로 이동시킵니다
• moveBack - 봇을 뒤로 이동시킵니다
• turnLeft - 봇을 좌회전시킵니다
• turnRight - 봇을 오른쪽으로 돌립니다
• placeBlock - 지정된 좌표에 블록을 배치합니다.
• digBlock - 지정된 좌표에서 블록을 끊습니다.
• getBlockInfo - 지정된 좌표에 있는 블록에 대한 정보를 가져옵니다.
• selectSlot - 핫바 슬롯 선택(0-8)
• getInventory - 봇의 인벤토리 내용을 가져옵니다.
• equipItem - 지정된 목적지에 이름으로 아이템을 장착합니다.
• getStatus - 봇의 현재 상태(건강, 음식, 위치 등)를 가져옵니다.
• getNearbyEntities - 범위 내 근처 엔터티 목록 가져오기
• attack - 근처의 엔티티를 이름으로 공격합니다.
• useItem - 현재 보유한 아이템을 사용/활성화합니다.
• stopUsingItem - 현재 항목 사용 중지/비활성화
• lookAt - 봇이 특정 좌표를 바라보도록 합니다.
• followPlayer - 특정 플레이어 팔로우
• stopFollowing - 현재 대상을 팔로우 중지합니다.
• goToPosition - 특정 좌표로 이동

기술적 세부 사항

• 로컬 개발을 위해 서버가 오프라인 모드로 실행됩니다.
• 기본 메모리 할당: 2GB
• 기본 포트: 25565
• 봇 사용자 이름: MCPBot

문제 해결

일반적인 문제

1. MCP 연결에 실패했습니다
   • 남아 있는 Java 프로세스를 찾으세요
   • 수동으로 종료하세요:
     • Windows: 작업 관리자 사용(테스트되지 않음)
     • 맥/리눅스:
       • '활동 모니터'로 가서 '강제 종료' 자바를 실행하세요.
   • 프로세스 종료에 실패하면 컴퓨터를 다시 시작하세요.
   • 참고: 최신 버전에서는 이러한 문제가 자동으로 해결됩니다.
2. 서버가 시작되지 않습니다
   • Java가 설치되어 있는지 확인하세요
   • server.jar 경로가 올바른지 확인하세요
   • 포트 25565를 사용할 수 있는지 확인하세요
3. 서버에 연결할 수 없습니다
   • 서버가 실행 중인지 확인하세요(로그 확인)
   • "localhost"를 서버 주소로 사용하고 있는지 확인하세요.
   • 방화벽 설정을 확인하세요

로그 위치

• Minecraft 서버 로그: minecraft-server 디렉토리 확인
• Claude Desktop 로그: ~/Library/Logs/Claude/mcp*.log

기여하다

크고 작음에 상관없이 기부를 환영합니다!

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.