minecraft-paper-mcp

MCP-сервер для управления администрированием/бэкендом Paper Minecraft server — запускается на той же машине, что и сам 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 (grep по регулярному выражению)

Related MCP server: Minecraft Server MCP

Установка

Требуется 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 доступен извне, его нужно закрыть файрволом — RCON не шифрует трафик. Сервер должен слушать только 127.0.0.1 (значение по умолчанию), если MCP-сервер работает на той же машине.

3. Перезапустите Paper server один раз, чтобы настройки RCON вступили в силу.

Настройка переменных окружения

Имеется файл .env.example для справки — скопируйте его в .env и укажите реальные значения (файл .env добавлен в .gitignore и не будет закоммичен на GitHub). Сам MCP-сервер не загружает .env автоматически (dotenv не используется) — задавайте значения через env в claude_desktop_config.json или экспортируйте переменные перед реальным запуском. .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 workflow (.github/workflows/build.yml), который при каждом push или открытии PR в main запускает npm install + npm run build на Node 18.x и 20.x, чтобы проверить, что проект собирается. Если вы хотите использовать npm ci вместо npm install, сначала один раз выполните npm install локально, чтобы создать package-lock.json, и закоммитьте этот файл в репозиторий.

Примечания / Предостережения

• server_start и server_restart запускают процесс в detached-режиме и сохраняют PID в MC_PID_FILE. Это можно использовать и для запуска в качестве настоящего сервиса (systemd), но MCP-сервер не будет знать о процессах, созданных самим systemd. Выберите какой-то один подход — либо этот MCP сам запускает/останавливает процесс, либо systemd управляет им, и используются только те инструменты, которые работают через RCON/файлы.

• server_stop сначала попытается отправить команду stop через RCON (graceful shutdown); если подключиться к RCON не удаётся, используется запасной вариант с SIGTERM.

• server_properties_set изменяет файл напрямую — перезапуск сервера придётся выполнить самостоятельно (автоматического перезапуска не будет).

• Команды ban/kick/whitelist выполняются через RCON, а не напрямую правят JSON-файлы — это безопаснее, пока сервер работает.