Servidor MCP de ejecución de comandos de Minecraft

Un servidor MCP (Model Context Protocol) que permite a Claude ejecutar comandos de Minecraft y obtener autocompletado mediante la API de MasterControl.

Características

Este servidor MCP proporciona dos herramientas:

1. execute_command

Ejecuta cualquier comando de Minecraft de forma remota como el jugador autenticado.

• El jugador debe estar en línea y en un servidor

• El jugador recibe una notificación en el juego cuando se ejecutan los comandos

• Devuelve la salida del comando o mensajes de error

• Para obtener ayuda: Añade "help" a cualquier comando (ej. "island help", "island upgrade help")

Ejemplos:

execute_command("gamemode creative")
execute_command("island help")              # Shows island command help
execute_command("island upgrade help")      # Shows upgrade subcommand help
execute_command("island upgrade speed 5")

2. tab_complete

Obtén sugerencias de autocompletado para comandos parciales.

• Descubre comandos y subcomandos disponibles

• Encuentra argumentos y parámetros válidos

• Funciona exactamente igual que pulsar Tab en Minecraft

Ejemplos:

tab_complete("gamemode ")   # Returns: survival, creative, adventure, spectator
tab_complete("island ")     # Returns: available island subcommands

Related MCP server: MCP Minecraft Remote

Requisitos previos

• Python 3.10 o superior

• Gestor de paquetes uv (instalar aquí)

• Un servidor MasterControl en ejecución con la API de comandos

• Clave de API válida para tu jugador de Minecraft

Instalación

1. Clona el repositorio:

git clone https://github.com/<your-user>/minecraft-mcp-server.git
cd minecraft-mcp-server

2. Instala las dependencias:

uv sync

3. Configura las variables de entorno:

cp .env.example .env

4. Edita .env con tus ajustes:

# Required: Your Midnight API key
MIDNIGHT_API_KEY=your-api-key-here

# Optional: MasterControl API URL (defaults to localhost:8080)
MIDNIGHT_API_URL=http://your-server:8080/api/v2

Uso

Pruebas locales

Ejecuta el servidor directamente para probar:

uv run server.py

Esperará la entrada por stdio; eso es lo esperado para un servidor MCP. Ctrl+C para salir.

Integración con Claude Code

Añade el servidor a Claude Code (usa la ruta absoluta a tu repositorio clonado):

claude mcp add midnight \
  --transport stdio \
  --env MIDNIGHT_API_KEY=your-key-here \
  --env MIDNIGHT_API_URL=http://localhost:8080/api/v2 \
  -- uv --directory /absolute/path/to/minecraft-mcp-server run server.py

Verificar la instalación

En Claude Code, comprueba que el servidor se está ejecutando:

/mcp

Deberías ver midnight listado con el estado ✓ Connected.

Ejemplos de conversaciones

Ejecutar comandos:

You: "Change my gamemode to creative"
Claude: [Uses execute_command("gamemode creative")]
        ✓ Command executed successfully

Obtener ayuda de comandos:

You: "How do I use the island upgrade command?"
Claude: [Uses execute_command("island upgrade help")]
        Shows the help output for island upgrade

Explorar comandos:

You: "What island commands are available?"
Claude: [Uses tab_complete("island ")]
        Lists: upgrade, create, delete, invite, members...

Configuración

Variables de entorno

Endpoints de la API

• POST /api/v2/command/execute — Ejecutar comandos

• POST /api/v2/command/tabComplete — Obtener autocompletado

Solución de problemas

"MIDNIGHT_API_KEY environment variable not set!"

Crea un archivo .env:

echo "MIDNIGHT_API_KEY=your-key-here" > .env

"Failed to execute command"

Comprueba que:

1. La API de MasterControl esté en ejecución

2. La clave de API sea correcta

3. El jugador esté en línea y en un servidor (no en el limbo del proxy)

Seguridad

• Nunca subas .env al repositorio — contiene tu clave de API (ya excluida mediante .gitignore)

• Los comandos se ejecutan con los permisos de tu jugador

• La IA puede ejecutar cualquier comando que tú puedas ejecutar en el juego