Minecraft MCP 서버

https://github.com/user-attachments/assets/6f17f329-3991-4bc7-badd-7cde9aacb92f

거대 언어 모델과 Mineflayer API로 구동되는 Minecraft 봇입니다. 이 봇은 Model Context Protocol (MCP)을 사용하여 Claude 및 기타 지원되는 모델이 Minecraft 캐릭터를 제어할 수 있도록 합니다.

사전 요구 사항

• Git

• Node.js (>= 20.10.0)

• 실행 중인 Minecraft 게임 (아래 설정은 Microsoft Game Pass에 포함된 Minecraft 1.21.8 Java Edition으로 테스트되었습니다)

• MCP 호환 클라이언트. Claude Desktop을 예로 들지만, 다른 MCP 클라이언트도 지원됩니다.

Related MCP server: MCP Server

시작하기

이 봇은 Model Context Protocol (MCP)을 통해 Claude Desktop과 함께 사용하도록 설계되었습니다.

Minecraft 실행

싱글 플레이어 월드를 생성하고 LAN에 공개(ESC -> LAN 서버 열기)합니다. 봇은 포트 25565와 호스트 이름 localhost를 사용하여 연결을 시도합니다. 이러한 매개변수는 다음 단계에서 claude_desktop_config.json에 구성할 수 있습니다.

MCP 구성

Claude Desktop이 설치되어 있는지 확인하세요. 파일 -> 설정 -> 개발자 -> 구성 편집을 엽니다. 설치 디렉토리가 열릴 것입니다. claude_desktop_config.json이라는 이름의 파일을 찾아 다음 코드를 삽입하세요:

{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": [
        "-y",
        "github:yuniko-software/minecraft-mcp-server",
        "--host",
        "localhost",
        "--port",
        "25565",
        "--username",
        "ClaudeBot"
      ]
    }
  }
}

올바른 --port 및 --host 매개변수가 사용되었는지 다시 확인하세요. Claude Desktop 애플리케이션을 완전히 재부팅(OS 트레이에서 닫아야 함)해야 합니다.

실행

Minecraft 게임이 실행 중이고 월드가 LAN에 공개되어 있는지 확인하세요. 그런 다음 Claude Desktop 애플리케이션을 시작하면 봇이 게임에 참여할 것입니다.

Claude Desktop이 MCP 서버를 부팅하는 데 시간이 걸릴 수 있습니다. 서버가 성공적으로 부팅되었다는 표시는 다음과 같습니다:

활성 Claude Desktop 채팅을 통해 봇에게 명령을 내릴 수 있습니다. 또한 건물 이미지를 업로드하고 봇에게 건설하도록 요청할 수도 있습니다 😁

프롬프트에 봇이 Minecraft에서 무언가를 해야 한다는 점을 언급하는 것을 잊지 마세요. 이것이 MCP 서버를 실행하는 트리거이기 때문입니다. 권한을 요청할 것입니다.

Claude Sonnet을 사용하면 흥미로운 결과를 얻을 수 있습니다. 봇 에이전트가 매우 똑똑해질 것입니다 🫡

사용 예시: 공유된 Claude 채팅

사용 가능한 명령

Minecraft 서버에 연결되면 Claude는 다음 명령을 사용할 수 있습니다:

이동

• get-position - 봇의 현재 위치 가져오기

• move-to-position - 특정 좌표로 이동

• look-at - 봇이 특정 좌표를 바라보게 하기

• jump - 봇이 점프하게 하기

• move-in-direction - 특정 방향으로 일정 시간 동안 이동

비행

• fly-to - 봇이 특정 좌표로 직접 날아가게 하기

인벤토리

• list-inventory - 봇 인벤토리의 모든 아이템 나열

• find-item - 인벤토리에서 특정 아이템 찾기

• equip-item - 특정 아이템 장착

블록 상호작용

• place-block - 지정된 좌표에 블록 배치

• dig-block - 지정된 좌표의 블록 파기

• get-block-info - 블록에 대한 정보 가져오기

• find-blocks - 특정 유형의 근처 블록 하나 이상 찾기

화로

• smelt-item - 화로와 같은 블록을 사용하여 아이템 제련

엔티티 상호작용

• find-entity - 특정 유형의 가장 가까운 엔티티 찾기

통신

• send-chat - 게임 내 채팅 메시지 보내기

• read-chat - 플레이어의 최근 채팅 메시지 가져오기

게임 상태

• detect-gamemode - 게임의 게임 모드 감지

기여

개선을 위한 풀 리퀘스트를 제출하거나 이슈를 자유롭게 열어주세요. 모든 리팩토링 커밋, 기능 및 테스트 기여, 이슈 및 토론은 대단히 환영합니다!

기여를 시작하려면 CONTRIBUTING.md를 참조하세요.

⭐ 이 프로젝트가 유용하다고 생각되시면 GitHub에서 별표를 눌러주세요! ⭐

여러분의 지원은 이 프로젝트가 혜택을 받을 수 있는 다른 사람들에게 더 잘 알려지도록 돕습니다.