minecraft-platform

Hermes Minecraft Gateway ⛏️

A first-class Hermes Agent platform plugin that lets you chat with Hermes directly inside Minecraft.

Join a Minecraft server with a Mineflayer bot, and every player gets their own Hermes session — same features as Discord, Telegram, or WhatsApp. Tools, commands, code execution, file editing — all accessible from in-game chat.

Features

Per-player sessions — each player gets their own Hermes session (like DMs on Discord)
Full command support — $new, $help, $model, $stop all work in chat
Plain text responses — no markdown, no formatting codes (servers reject them)
Public chat responses — Hermes replies in public chat
Private tool progress — terminal/file operations go via /tell private whisper
Auto-wander — the bot wanders, jumps, and looks at nearby players
256-char chunking — long responses split with [1/3] markers
Configurable prefix — $command syntax keeps server commands from conflicting
Offline or Microsoft auth — supports both offline and online-mode servers
Persistence — survives gateway restarts via systemd drop-in

Quick Start

Prerequisites

Hermes Agent installed and running (hermes gateway run)
Node.js >= 22
A Minecraft server (offline or online mode)
Python 3.12+

Installation

The plugin lives at ~/.hermes/plugins/minecraft/. Install it:

# Clone or copy the plugin
git clone https://github.com/kyssta-exe/hermes-minecraft-gateway ~/.hermes/plugins/minecraft
# or symlink:
ln -sf /path/to/hermes-minecraft-gateway ~/.hermes/plugins/minecraft

# Install Node dependencies
cd ~/.hermes/plugins/minecraft/bridge
npm install --production --no-audit --no-fund

Configuration

Set environment variables (via systemd drop-in, .env, or hermes config):

export MINECRAFT_ENABLED=true
export MINECRAFT_SERVER=your.server.ip
export MINECRAFT_PORT=25565
export MINECRAFT_USERNAME=HermesBot
export MINECRAFT_AUTH=offline    # or "microsoft"
export MINECRAFT_PREFIX=$        # prefix for Hermes commands ($new, $help)
export MINECRAFT_ALLOW_ALL_USERS=true

Or create a systemd drop-in at ~/.config/systemd/user/hermes-gateway.service.d/minecraft.conf:

[Service]
Environment="MINECRAFT_ENABLED=true"
Environment="MINECRAFT_SERVER=your.server.ip"
Environment="MINECRAFT_PORT=25565"
Environment="MINECRAFT_USERNAME=HermesBot"
Environment="MINECRAFT_AUTH=offline"
Environment="MINECRAFT_ALLOW_ALL_USERS=true"
Environment="MINECRAFT_PREFIX=$"

Starting

# Reload systemd, then restart gateway
systemctl --user daemon-reload
systemctl --user restart hermes-gateway

# Or if running in foreground:
hermes gateway restart

Usage

Join your Minecraft server. The bot (HermesBot) will be wandering around.

| What to type | What happens |
|---|---|
| hi | Hermes replies in public chat |
| $new | Reset your session |
| $help | Show available commands |
| $model | Show current LLM model |
| write a poem | Hermes writes and responds |
| what's the time? | Hermes checks and replies |

Tip: The $ prefix is only needed for commands. Regular chat goes straight to Hermes.

Configuration Reference

| Variable | Default | Description |
|---|---|---|
| MINECRAFT_ENABLED | — | Required: true to enable the adapter |
| MINECRAFT_SERVER | — | Required: Minecraft server hostname/IP |
| MINECRAFT_PORT | 25565 | Server port |
| MINECRAFT_USERNAME | HermesBot | Bot's in-game username |
| MINECRAFT_AUTH | offline | offline or microsoft |
| MINECRAFT_PREFIX | `` (none) | Command prefix ($new, $help). Empty = no prefix |
| MINECRAFT_PRIVATE_MESSAGES | false | true = all replies via /tell private |
| MINECRAFT_BRIDGE_PORT | 13000 | Internal bridge HTTP port |
| MINECRAFT_ALLOWED_USERS | — | Comma-separated allowlist of usernames |
| MINECRAFT_ALLOW_ALL_USERS | false | true = any player can use the bot |
| MINECRAFT_HOME_CHANNEL | — | Default player for cron/notification delivery |

Architecture

Minecraft Server
      ↑ Mineflayer (TCP/MC protocol)
      ↓
Node.js Bridge (bridge/index.js)
  - Mineflayer bot
  - HTTP server (health, messages, send)
  - Idle wander loop
      ↑ HTTP poll (500ms)
      ↓
Python Adapter (adapter.py)
  - Hermes BasePlatformAdapter
  - Per-player session management
  - Message chunking (256-char limit)
  - § formatting / markdown conversion
      ↑
      ↓
Hermes Gateway
  - LLM + tools
  - Command dispatch
  - Session persistence

File Structure

hermes-minecraft-gateway/
├── README.md              # You are here
├── LICENSE                # MIT
├── CHANGELOG.md           # Release history
├── plugin.yaml            # Hermes plugin metadata
├── __init__.py            # Plugin entry point
├── adapter.py             # Python adapter (gateway integration)
├── bridge/
│   ├── package.json       # Node deps
│   └── index.js           # Mineflayer bot + HTTP bridge
├── docs/
│   ├── setup.md           # Detailed setup guide
│   ├── commands.md        # Command reference
│   ├── configuration.md   # All config options
│   ├── architecture.md    # Architecture deep-dive
│   └── formatting.md      # Minecraft § codes reference
└── scripts/
    └── install.sh         # One-shot install script

Development

# Clone the repo
git clone https://github.com/kyssta-exe/hermes-minecraft-gateway
cd hermes-minecraft-gateway

# Install Python deps (none extra — uses Hermes gateway packages)
# Install Node deps
cd bridge && npm install

# Symlink to Hermes plugins
ln -sf $PWD ~/.hermes/plugins/minecraft

# Set env vars and restart gateway
hermes gateway restart

Version History

See CHANGELOG.md.

License

MIT © Kyssta

README from the reviewed commit 8ff37a6; it updates when the author re-pins.

About