minecraft-paper-mcp

Paper Minecraft 서버 백엔드 관리를 위한 MCP 서버 — Minecraft 서버와 같은 머신에서 실행됩니다 (파일에 직접 접근하고 프로세스를 직접 제어할 수 있음) RCON을 통한 게임 내 명령어와 함께 사용합니다

기능

• 프로세스 제어: server_start, server_stop, server_restart, server_status

• RCON / 게임 내 명령어: rcon_command (모든 원시 명령어), players_list, server_tps, server_say, player_kick, player_ban, player_pardon, player_op, player_deop, whitelist_add, whitelist_remove, give_item, teleport_player, set_gamerule, set_weather, set_time

• 파일 읽기: whitelist_list, ops_list, banned_players_list, banned_ips_list, server_properties_get, server_properties_set (적용하려면 재시작 필요)

• 로그: logs_tail (최근 N줄 로그 보기), logs_search (regex로 grep)

Related MCP server: Minecraft Server MCP

설치

Node.js 18 이상 필요

cd minecraft-mcp
npm install
npm run build

Paper 서버 준비

1. Paper 서버의 server.properties에서 RCON을 활성화합니다:

   enable-rcon=true
   rcon.port=25575
   rcon.password=ใส่รหัสผ่านที่ตั้งเอง_อย่าใช้ค่าว่าง

2. 중요: RCON 포트가 외부에 노출될 수 있다면 방화벽으로 차단해야 합니다 — RCON은 암호화되지 않습니다 MCP 서버가 같은 머신에서 실행된다면 127.0.0.1 (기본값)에서만 수신하도록 해야 합니다

3. RCON 설정이 적용되도록 Paper 서버를 한 번 재시작합니다

환경 변수 설정

참고용으로 .env.example 파일이 있습니다 — .env로 복사한 후 실제 값을 입력합니다 (.env 파일은 .gitignore에 포함되어 있어 GitHub에 커밋되지 않습니다) MCP 서버 자체는 .env를 자동으로 로드하지 않습니다 (dotenv를 사용하지 않음) — claude_desktop_config.json의 env를 통해 설정하거나 실제 실행 전에 변수를 export하세요. .env는 자신을 위한 메모용일 뿐입니다

Claude Desktop 설정

claude_desktop_config.json에 추가합니다:

{
  "mcpServers": {
    "minecraft-paper": {
      "command": "node",
      "args": ["/absolute/path/to/minecraft-mcp/build/index.js"],
      "env": {
        "MC_SERVER_DIR": "/absolute/path/to/paper-server",
        "MC_START_COMMAND": "java -Xmx6G -Xms2G -jar paper-1.21.jar nogui",
        "MC_RCON_PASSWORD": "รหัสผ่านเดียวกับใน server.properties"
      }
    }
  }
}

그런 다음 Claude Desktop을 재시작합니다

CI

GitHub Actions 워크플로우 (.github/workflows/build.yml)가 있으며, main 브랜치에 push하거나 PR을 열 때마다 Node 18.x 및 20.x에서 npm install + npm run build를 실행하여 프로젝트가 빌드되는지 확인합니다. npm install 대신 npm ci를 사용하려면 로컬에서 npm install을 한 번 실행하여 package-lock.json을 생성한 후 해당 파일을 repo에 커밋하세요

참고 사항 / 주의사항

• server_start/server_restart는 분리된(detached) 프로세스를 생성하고 PID를 MC_PID_FILE에 저장합니다 — 실제 서비스(systemd)로 실행하는 경우에도 사용할 수 있지만, MCP는 systemd가 생성한 프로세스를 인식하지 못합니다. 한 가지 방법을 선택하세요 (MCP가 직접 start/stop을 관리하거나, systemd가 관리하고 RCON/파일에 의존하는 도구만 사용)

• server_stop은 먼저 RCON을 통해 stop 명령어를 보내려고 시도합니다 (정상 종료) RCON에 연결할 수 없으면 SIGTERM으로 대체합니다

• server_properties_set은 파일을 직접 수정하므로 적용하려면 서버를 직접 재시작해야 합니다 (자동 재시작하지 않음)

• ban/kick/whitelist 명령어는 RCON을 통해 수행되며 json 파일을 직접 수정하지 않습니다 — 서버가 실행 중일 때 더 안전합니다