⛏️ Minecraft MCP 서버 — AI 기반 마인크래프트 에이전트

제작: Soumyadeep, AI/ML 리드

이것은 무엇인가요?

이것은 Model Context Protocol (MCP) 기반의 마인크래프트용 AI 에이전트입니다. MCP 호환 AI 클라이언트(Claude Desktop, Cursor, Kiro, Windsurf 등)를 마인크래프트 월드에 직접 연결하여 AI를 완벽한 기능을 갖춘 게임 내 봇으로 변환합니다.

AI는 이동, 건축, 제작, 채팅이 가능하며, 이제는 단일 명령어로 스키마틱 파일에서 전체 구조물을 즉시 생성할 수도 있습니다.

Related MCP server: Renge Bot

✨ 새로운 기능 — 스키마틱 빌더 (핵심 기능)

이 포크의 가장 큰 추가 사항은 스키마틱 빌더 시스템입니다. 이는 AI가 .schem / .schematic 파일을 사용하여 거대하고 복잡한 구조물을 몇 초 만에 건설할 수 있게 해주는 3가지 새로운 MCP 도구 세트입니다.

AI가 place-block을 수백 번 반복 호출(느리고, 오류가 발생하기 쉬우며, 잘못될 가능성이 높음)하는 대신, 이제는 다음과 같이 작동합니다:

1. 번들로 제공된 스키마틱 파일 라이브러리 확인

2. 파일을 파싱하여 크기와 블록 구성 파악

3. 봇을 통해 /setblock 명령 스트림을 실행하여 크리에이티브 모드에서 전체 구조물을 즉시 건설 — 인벤토리, 경로 탐색, 실패 없음

3가지 새로운 도구

지원되는 형식

AI 사용 방법

AI는 항상 번들 라이브러리를 먼저 확인하도록 지시받습니다. 따라서 다음과 같이 말하면:

"내 근처에 바이킹 집을 지어줘"

AI는 다음과 같이 작동합니다:

1. list-schematics 호출 → viking-house1 발견

2. schematic-info("viking-house1") 호출 → 크기 읽기

3. build-schematic("viking-house1", x, y, z) 호출 → 즉시 생성

수동 블록 배치는 없습니다. 환각으로 인한 기하학적 오류도 없습니다. 단 몇 초 만에 실제 사람이 설계한 구조물이 완성됩니다.

🛠️ 전체 도구 참조

이동

건축 (스키마틱)

블록

인벤토리 및 제작

엔티티 및 채팅

🚀 설정 가이드

사전 요구 사항

• Node.js ≥ 20.10.0

• Git

• Minecraft Java Edition (1.21.x에서 테스트됨)

• MCP 호환 AI 클라이언트 (Claude Desktop, Cursor, Kiro 등)

1단계 — 복제 및 설치

git clone https://github.com/soumyadeo/minecraft-mcp-server.git
cd minecraft-mcp-server
npm install

2단계 — 빌드

npm run build

이 명령은 TypeScript를 dist/main.js로 컴파일합니다.

3단계 — 스키마틱 파일 추가 (권장)

프로젝트 루트의 schematics/ 폴더에 .schem 파일을 넣으세요:

minecraft-mcp-server/
  schematics/
    smallhouse1.schem       ← already included
    viking-house1.schematic ← already included
    my-castle.schem         ← add your own!

AI는 list-schematics를 통해 자동으로 파일을 발견합니다.

4단계 — MCP 클라이언트 구성

Claude Desktop

File → Settings → Developer → Edit Config를 열고 다음을 추가하세요:

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "C:\\path\\to\\minecraft-mcp-server\\dist\\main.js",
        "--host", "localhost",
        "--port", "25565",
        "--username", "ClaudeBot"
      ]
    }
  }
}

Cursor / VS Code (mcp.json)

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "C:\\path\\to\\minecraft-mcp-server\\dist\\main.js",
        "--host", "localhost",
        "--port", "25565",
        "--username", "ClaudeBot"
      ],
      "type": "stdio"
    }
  }
}

C:\path\to\를 실제 컴퓨터 경로로 바꾸세요.

5단계 — 마인크래프트 시작

1. Minecraft Java Edition 실행

2. 싱글플레이어 월드 열기 또는 생성

3. ESC → LAN 서버 열기 클릭

4. 표시된 포트 번호 확인 (보통 25565)

5. 채팅창에서 봇에게 운영자 권한 부여:

   /op ClaudeBot

   ⚠️ 스키마틱 빌더가 사용하는 /setblock 명령이 작동하려면 운영자 권한이 필수입니다.

6단계 — AI 클라이언트 재시작 및 테스트

MCP 클라이언트를 완전히 재시작하세요(필요시 시스템 트레이에서 종료). 봇이 자동으로 게임에 참여해야 합니다.

테스트 프롬프트:

"사용 가능한 스키마틱을 확인하고 내 현재 위치에 smallhouse를 지어줘."

📦 스키마틱 추가하기

스키마틱 라이브러리는 단순한 폴더입니다. 구조물을 더 추가하려면:

1. 온라인에서 .schem 파일 찾기:

   • Planet Minecraft — "schematic"으로 검색 및 필터링

   • Minecraft-Schematics.com

   • 게임 내 WorldEdit의 //copy + //schem save 명령 사용

2. minecraft-mcp-server/schematics/ 폴더에 파일 넣기

3. MCP 서버 재시작

AI가 즉시 인식하며, 코드 변경은 필요 없습니다.

⚙️ 서버 인수

node dist/main.js --host localhost --port 25565 --username ClaudeBot

🏗️ 아키텍처

src/
  main.ts                   — MCP server entry point, tool registration
  bot-connection.ts         — Mineflayer bot lifecycle management
  tool-factory.ts           — MCP tool registration wrapper
  tools/
    schematic-tools.ts      — ★ Schematic builder (new)
    block-tools.ts          — Block placement & digging
    position-tools.ts       — Movement & pathfinding
    inventory-tools.ts      — Inventory management
    crafting-tools.ts       — Recipe lookup & crafting
    furnace-tools.ts        — Smelting
    entity-tools.ts         — Entity detection
    chat-tools.ts           — In-game chat
    flight-tools.ts         — Flight control
    gamestate-tools.ts      — Game mode detection
schematics/                 — Bundled schematic file library
  smallhouse1.schem
  viking-house1.schematic

주요 라이브러리:

• mineflayer — 마인크래프트 봇 프레임워크

• prismarine-schematic — 스키마틱 파일 파서

• mineflayer-pathfinder — 경로 탐색

• @modelcontextprotocol/sdk — MCP 서버 SDK

yuniko-software/minecraft-mcp-server에서 포크 및 확장됨

🗺️ 로드맵

• [ ] mode: "bot_place" — mineflayer-builder를 통한 물리적 서바이벌 모드 건축

• [ ] @kleppe/litematic-reader를 통한 .litematic 형식 지원

• [ ] search-and-build 도구 — 키워드로 스키마틱 검색 및 다운로드

• [ ] run-builder-script — 절차적 빌드 스크립트 실행 (피라미드, 돔 등)

• [ ] 상자 및 저장소 도구

• [ ] 주민 거래 도구

• [ ] 전투 및 생존 도구

🤝 기여하기

풀 리퀘스트를 환영합니다! 가이드라인은 CONTRIBUTING.md를 참조하세요.

📄 라이선스

MIT — LICENSE 참조

제작 및 확장: Soumyadip Debnath, AI/ML 리드 원본 프로젝트: Yuniko Software