Minecraft Ops MCP

Un servicio MCP stdio orientado a la gestión y operación de servidores de Minecraft. La versión actual está implementada basada en el SDK oficial de MCP para Python, con adaptaciones de backend para:

• API de MCSManager: ciclo de vida de instancias, registros, gestión de archivos, comandos de consola.

• RCON: respaldo para comandos de consola tradicionales.

• Minecraft Server Management Protocol (MSMP): protocolo de gestión JSON-RPC sobre WebSocket para Minecraft Java 1.21.9+.

Documentación

• Manual de usuario: docs/USER_MANUAL.md

• Guía del marco de desarrollo: docs/DEVELOPER_GUIDE.md

• Limitaciones actuales y hoja de ruta: docs/LIMITATIONS.md

• Informe de pruebas de integración: docs/TEST_REPORT_2026-04-14.md

• Lista de verificación de lanzamiento: docs/RELEASE_CHECKLIST.md

• Notas de seguridad: SECURITY.md

• Registro de cambios: CHANGELOG.md

Cómo ejecutar

Se recomienda instalar las dependencias del proyecto en el entorno de Python actual antes de ejecutar:

cd /home/damoc/codes/minecraft-ops-mcp
python3 -m pip install -e .
minecraft-ops-mcp

Para el desarrollo y la depuración, también se puede especificar explícitamente PYTHONPATH:

cd /home/damoc/codes/minecraft-ops-mcp
PYTHONPATH=src python3 -m minecraft_ops_mcp

Desarrollo y pruebas

Pruebas unitarias:

cd /home/damoc/codes/minecraft-ops-mcp
PYTHONPATH=src python3 -B -m unittest discover -s tests

Comprobación de sintaxis:

python3 -m compileall -q src scripts

Las sondas de integración a nivel de protocolo se pueden encontrar en docs/TEST_REPORT_2026-04-14.md y docs/RELEASE_CHECKLIST.md.

Ejemplo de configuración del cliente MCP

{
  "mcpServers": {
    "minecraft-ops": {
      "command": "python3",
      "args": ["-m", "minecraft_ops_mcp"],
      "cwd": "/home/damoc/codes/minecraft-ops-mcp",
      "env": {
        "PYTHONPATH": "src",
        "MCSM_BASE_URL": "http://127.0.0.1:23333",
        "MCSM_API_KEY": "replace-me",
        "MCSM_DEFAULT_DAEMON_ID": "replace-me",
        "MCSM_DEFAULT_INSTANCE_UUID": "replace-me",
        "RCON_HOST": "127.0.0.1",
        "RCON_PORT": "25575",
        "RCON_PASSWORD": "replace-me",
        "MSMP_URL": "ws://127.0.0.1:25585",
        "MSMP_SECRET": "replace-me",
        "MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST": "list,time,help",
        "MINECRAFT_OPS_RAW_COMMAND_DENYLIST": "stop,op,deop,ban,ban-ip"
      }
    }
  }
}

También puede consultar .env.example y colocar las variables en la configuración de su cliente MCP. El servicio en sí no leerá automáticamente el archivo .env para evitar que el origen de la configuración en tiempo de ejecución se vuelva implícito.

Herramientas principales

MCSManager:

• server.list_daemons

• server.get_daemon_system

• server.list_instances

• server.get_instance

• server.start

• server.stop

• server.restart

• server.kill

• server.send_command

• server.get_logs

• instance.create

• instance.update_config

• instance.update_config_patch

• instance.clone_from_template

• instance.delete

• instance.reinstall

• instance.run_update_task

• file.list

• file.read

• file.download_prepare

• file.download_local

• file.upload_prepare

• file.upload_local

• file.upload_url

• file.write

• file.write_new

• file.delete

• file.move

• file.copy

• file.mkdir

• file.touch

• file.compress

• file.uncompress

Herramientas convenientes entre backends:

• server.save_world: prioridad MSMP, seguido de RCON, luego MCSManager.

• server.broadcast: prioridad MSMP, seguido de RCON, luego MCSManager.

RCON:

• rcon.command

• rcon.list_players

• rcon.time_query

• rcon.save_all

MSMP:

• msmp.discover

• msmp.call

• msmp.players.list

• msmp.players.kick

• msmp.server.status

• msmp.server.save

• msmp.server.stop

• msmp.bans.get

• msmp.bans.add

• msmp.bans.remove

• msmp.bans.set

• msmp.bans.clear

• msmp.ip_bans.get

• msmp.ip_bans.add

• msmp.ip_bans.remove

• msmp.ip_bans.set

• msmp.ip_bans.clear

• msmp.allowlist.get

• msmp.allowlist.add

• msmp.allowlist.remove

• msmp.allowlist.set

• msmp.allowlist.clear

• msmp.operators.get

• msmp.operators.add

• msmp.operators.remove

• msmp.operators.set

• msmp.operators.clear

• msmp.gamerules.get

• msmp.gamerules.update

• msmp.server_settings.get

• msmp.server_settings.list

• msmp.server_settings.set

Política de seguridad

Las operaciones de alto riesgo requieren parámetros explícitos:

{ "confirm": true }

Si solo desea que el agente explique primero lo que hará, pase:

{ "dry_run": true }

Las herramientas de alto riesgo incluyen el inicio/parada/reinicio/kill de instancias, comandos sin procesar, escritura/eliminación/movimiento/compresión/descompresión/carga de archivos, descarga a la máquina local de MCP, expulsión, baneo, modificaciones de lista blanca/OP/reglas de juego/configuración del servidor, etc. Todas las llamadas a herramientas se registrarán en el registro de auditoría, ubicación predeterminada:

/tmp/minecraft-ops-mcp-audit.jsonl

Se puede desactivar configurando MINECRAFT_OPS_AUDIT_LOG= como vacío.

Los comandos sin procesar también pueden restringirse aún más mediante una lista de permitidos/denegados a nivel de prefijo:

MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST=list,time,help
MINECRAFT_OPS_RAW_COMMAND_DENYLIST=stop,op,deop,ban,ban-ip

Recomendaciones de backend

• Ciclo de vida de instancias, registros y gestión de archivos: utilice preferiblemente la API de MCSManager.

• Jugadores, lista blanca, OP, reglas de juego, configuración del servidor: utilice preferiblemente MSMP.

• Versiones antiguas del servidor o capacidades no cubiertas por MSMP: utilice RCON o el comando sin procesar de MCSManager como respaldo.

No exponga las claves de API de RCON, MSMP o MCSManager a la red pública. Es mejor que MSMP/RCON solo escuchen en localhost, VPN o túneles; para MCSManager se recomienda utilizar una clave de API con privilegios bajos.

Notas sobre los parámetros de MSMP

msmp.call pasará los params de JSON-RPC tal cual, lo cual es adecuado para nuevos métodos con diferencias significativas entre servidores/versiones:

{
  "method": "minecraft:server/status",
  "read_only": true
}

Para operaciones de escritura, utilice confirm=true o primero dry_run=true. read_only=true solo omitirá la confirmación para los métodos MSMP de solo lectura en la lista blanca, como rpc.discover, minecraft:players, minecraft:server/status, consultas de listas y lectura de configuraciones del servidor.