minecraft-paper-mcp

Servidor MCP para gestionar el backend de un servidor Paper Minecraft: se ejecuta en la misma máquina que el servidor de Minecraft (accede directamente a los archivos y controla el proceso) junto con comandos dentro del juego a través de RCON.

Funcionalidades

• Control de procesos: server_start, server_stop, server_restart, server_status

• RCON / comandos en el juego: rcon_command (cualquier comando en bruto), 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

• Lectura de archivos: whitelist_list, ops_list, banned_players_list, banned_ips_list, server_properties_get, server_properties_set (requiere reinicio para que surta efecto)

• Registros: logs_tail (ver las últimas N líneas del registro), logs_search (grep con regex)

Related MCP server: Minecraft Server MCP

Instalación

Se requiere Node.js 18 o superior.

cd minecraft-mcp
npm install
npm run build

Preparar el servidor Paper

1. Activa RCON en server.properties del servidor Paper:

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

2. Importante: si el puerto de RCON está expuesto al exterior, debes bloquearlo con un firewall — RCON no está cifrado. Debe escuchar solo en 127.0.0.1 (valor por defecto) si el servidor MCP se ejecuta en la misma máquina.

3. Reinicia el servidor Paper una vez para que la configuración de RCON surta efecto.

Configurar las variables de entorno

Hay un archivo .env.example como referencia: cópialo como .env e introduce los valores reales (el archivo .env está incluido en .gitignore, por lo que no se subirá a GitHub). El servidor MCP en sí no carga .env automáticamente (no usa dotenv) — configura los valores mediante env en claude_desktop_config.json o exporta las variables antes de ejecutarlo. .env sirve únicamente como referencia para ti.

Configurar en Claude Desktop

Añade lo siguiente en 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"
      }
    }
  }
}

Luego reinicia Claude Desktop.

CI

Hay un flujo de trabajo de GitHub Actions (.github/workflows/build.yml) que ejecuta npm install + npm run build en Node 18.x y 20.x cada vez que se hace push o se abre un PR hacia main para comprobar que el proyecto compila correctamente. Si quieres usar npm ci en lugar de npm install, ejecuta npm install una vez en tu máquina para generar package-lock.json y luego haz commit de ese archivo al repositorio antes.

Notas / precauciones

• server_start/server_restart generan un proceso desacoplado (detached) y guardan el PID en MC_PID_FILE — si quieres ejecutarlo como un servicio serio (systemd), también funciona, pero el MCP no reconocerá los procesos que cree systemd por su cuenta. Elige uno de los dos métodos (que este MCP inicie/detenga el proceso, o que systemd lo controle y uses solo las herramientas que dependen de RCON/archivos).

• server_stop intenta enviar el comando stop a través de RCON primero (apagado ordenado). Si no se puede conectar a RCON, recurre a SIGTERM.

• server_properties_set modifica el archivo directamente; debes reiniciar el servidor tú mismo para que surta efecto (no se reinicia automáticamente).

• Los comandos ban/kick/whitelist se ejecutan a través de RCON y no modifican los archivos json directamente — es más seguro cuando el servidor está en ejecución.