MCP-сервер для выполнения команд Minecraft

MCP-сервер (Model Context Protocol), который позволяет Claude выполнять команды Minecraft и получать автодополнение через API MasterControl.

Возможности

Этот MCP-сервер предоставляет два инструмента:

1. execute_command

Удаленное выполнение любой команды Minecraft от имени авторизованного игрока.

• Игрок должен быть онлайн и находиться на сервере

• Игрок получает внутриигровое уведомление при выполнении команд

• Возвращает результат выполнения команды или сообщения об ошибках

• Для получения справки: добавьте "help" к любой команде (например, "island help", "island upgrade help")

Примеры:

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

Получение подсказок автодополнения для неполных команд.

• Поиск доступных команд и подкоманд

• Поиск допустимых аргументов и параметров

• Работает точно так же, как нажатие клавиши Tab в Minecraft

Примеры:

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

Related MCP server: MCP Minecraft Remote

Предварительные требования

• Python 3.10 или выше

• Менеджер пакетов uv (установить здесь)

• Запущенный сервер MasterControl с API команд

• Действующий API-ключ для вашего игрока Minecraft

Установка

1. Клонируйте репозиторий:

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

2. Установите зависимости:

uv sync

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

cp .env.example .env

4. Отредактируйте .env с вашими настройками:

# 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

Использование

Локальное тестирование

Запустите сервер напрямую для тестирования:

uv run server.py

Он будет ожидать ввода через stdio — это стандартное поведение для MCP-сервера. Нажмите Ctrl+C для выхода.

Интеграция с Claude Code

Добавьте сервер в Claude Code (используйте абсолютный путь к клонированному репозиторию):

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

Проверка установки

В Claude Code проверьте, запущен ли сервер:

/mcp

Вы должны увидеть midnight в списке со статусом ✓ Connected.

Примеры диалогов

Выполнение команд:

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

Получение справки по команде:

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

Изучение команд:

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

Конфигурация

Переменные окружения

API-эндпоинты

• POST /api/v2/command/execute — Выполнение команд

• POST /api/v2/command/tabComplete — Получение автодополнения

Устранение неполадок

"MIDNIGHT_API_KEY environment variable not set!"

Создайте файл .env:

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

"Failed to execute command"

Убедитесь, что:

1. API MasterControl запущен

2. API-ключ верный

3. Игрок онлайн и находится на сервере (не в состоянии ожидания прокси)

Безопасность

• Никогда не добавляйте .env в репозиторий — он содержит ваш API-ключ (уже исключен через .gitignore)

• Команды выполняются с правами вашего игрока

• ИИ может выполнять любые команды, доступные вам в игре