minecraft-paper-mcp

MCP server สำหรับจัดการหลังบ้าน Paper Minecraft server — รันบนเครื่องเดียวกับตัว Minecraft server (เข้าถึงไฟล์และสั่ง process ได้ตรงๆ) ควบคู่กับคำสั่งในเกมผ่าน RCON

ความสามารถ

• ควบคุม process: 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 (ต้อง restart ถึงจะมีผล)
• Log: logs_tail (ดู log ล่าสุด N บรรทัด), logs_search (grep ด้วย regex)

ติดตั้ง

ต้องมี Node.js 18 ขึ้นไป

cd minecraft-mcp
npm install
npm run build

เตรียม Paper server

1. เปิด RCON ใน server.properties ของ Paper server:

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

2. สำคัญ: ถ้า RCON port เปิดสู่ภายนอกได้ ต้องปิดกั้นด้วย firewall — RCON ไม่ได้เข้ารหัส ควรให้ฟังเฉพาะ 127.0.0.1 (ค่าเริ่มต้น) ถ้า MCP server รันเครื่องเดียวกัน

3. Restart Paper server หนึ่งครั้งให้ค่า RCON มีผล

ตั้งค่า environment variables

มีไฟล์ .env.example ให้อ้างอิง — คัดลอกเป็น .env แล้วใส่ค่าจริง (ไฟล์ .env ถูกใส่ใน .gitignore แล้ว จะไม่ถูก commit ขึ้น GitHub) ตัว MCP server เองไม่ได้โหลด .env อัตโนมัติ (ไม่ได้ใช้ dotenv) — ตั้งค่าผ่าน env ใน claude_desktop_config.json หรือ export ตัวแปรก่อนรันจริง .env มีไว้เป็นที่จดค่าให้ตัวเองเท่านั้น

ตัวแปร	ค่าเริ่มต้น	คำอธิบาย
MC_SERVER_DIR	current dir	path ไปยังโฟลเดอร์ของ Paper server (ที่มี paper.jar, server.properties ฯลฯ)
MC_START_COMMAND	java -Xmx4G -Xms2G -jar paper.jar nogui	คำสั่งสำหรับ start server (ปรับ RAM/ชื่อ jar ตามจริง)
MC_RCON_HOST	127.0.0.1	host ของ RCON
MC_RCON_PORT	25575	port ของ RCON
MC_RCON_PASSWORD	(ว่าง)	รหัสผ่าน RCON — ต้องตั้งให้ตรงกับ server.properties
MC_PID_FILE	<MC_SERVER_DIR>/.mc-server.pid	ไฟล์เก็บ PID ของ process ที่ start ไว้

ตั้งค่าใน 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"
      }
    }
  }
}

แล้ว restart Claude Desktop

CI

มี GitHub Actions workflow (.github/workflows/build.yml) ที่รัน npm install + npm run build บน Node 18.x และ 20.x ทุกครั้งที่ push หรือเปิด PR เข้า main เพื่อเช็คว่าโปรเจกต์ build ผ่าน ถ้าต้องการใช้ npm ci แทน npm install ให้รัน npm install ในเครื่องตัวเองครั้งหนึ่งเพื่อสร้าง package-lock.json แล้ว commit ไฟล์นั้นเข้า repo ก่อน

หมายเหตุ / ข้อควรระวัง

• server_start/server_restart จะ spawn process แบบ detached แล้วเก็บ PID ไว้ใน MC_PID_FILE — ถ้าจะรันเป็น service จริงจัง (systemd) ก็ยังใช้ได้ แต่ตัว MCP จะไม่รู้จัก process ที่ systemd สร้างเอง ให้เลือกวิธีใดวิธีหนึ่ง (ให้ MCP นี้เป็นคน start/stop เอง หรือให้ systemd คุมแล้วใช้แค่ tool ที่พึ่ง RCON/ไฟล์)
• server_stop จะพยายามส่งคำสั่ง stop ผ่าน RCON ก่อน (graceful) ถ้าต่อ RCON ไม่ได้จะ fallback เป็น SIGTERM
• server_properties_set แก้ไฟล์ตรงๆ ต้อง restart server เองถึงจะมีผล (ไม่ auto-restart ให้)
• คำสั่ง ban/kick/whitelist ทำผ่าน RCON ไม่ได้แก้ไฟล์ json ตรงๆ — ปลอดภัยกว่าเวลา server กำลังรันอยู่