Bounded events, recoverable bridges
/api/events streams chat over authenticated SSE with bounded clients, replay, heartbeats, and an explicit reset path when a cursor is too old.
MCP SERVER · v3.1 · FLEET-AWARE MINEFLAYER
GIVE YOUR
AI AGENT
A FLEET IN
MINECRAFT_
39 MCP tools let Claude — or anything that speaks MCP — control Mineflayer bots, auto-assign shared work, recover fleet metadata safely after restarts, and stream live Minecraft events.
JAVA BOTS + BEDROCK PLAYERS
AUTO-ASSIGN + SAFE RECOVERY
SELF-HOSTED · LOOPBACK-FIRST
39 MCP TOOLS
Movement, mining, building, inventory, combat, chat, queues, fleet status, and waypoints.
~180 AUTOMATED TESTS
Current Node test suite, with environment-specific installer checks called out separately in CI.
NODE 20 + 22 CI
Lint, tests, documentation integrity, fleet coordination, and shell validation.
Bedrock client
Java client
→
Geyser /
Floodgate
Floodgate
→
PaperMC
:25565
:25565
←
Mineflayer
bot core
bot core
←
MCP :3100
(HTTP)
(HTTP)
←
AI agent
(Claude etc.)
(Claude etc.)
NEW DIFFERENTIATOR
MULTI-BOT WORK WITHOUT DUPLICATE CHAOS
OreMind now includes a process-local fleet coordinator. Agents can inspect one sanitized read model, auto-assign gather/build work to the least-loaded eligible bot, register shared waypoints, reserve known mutations, and opt movement into bounded corridor admission before Mineflayer receives a goal.
minecraft_fleet_status
minecraft_fleet_assign
minecraft_set_waypoint
minecraft_goto_waypoint
FLEET_RESERVATION_CONFLICT
MinerA
gather oak_log
gather oak_log
BuilderBot
blueprint lock
blueprint lock
Scout
waypoint base
waypoint base
OREMIND
fleet coordinator
fleet coordinator
LATEST FROM MAIN
THE PLATFORM MOVED FORWARD
The upstream OreMind repository is still shipping practical improvements around live operations, safe recovery, and contributor confidence.
Fleet metadata fails closed
Optional MCP_FLEET_STATE_FILE persistence restores waypoints and audit history safely; uncertain active assignments return as interrupted instead of replaying mutations.
Security maintenance is part of the product
The latest dependency update reaches patched Hono packages without a breaking downgrade. OreMind remains loopback-first, authenticated, and free of high/critical production advisories.
VIEW THE CHANGELOG →FROM CI-PROVEN TO WORLD-PROVEN
OreMind v3.1 is feature-complete for its current contract. The next release milestone is deliberately evidence-led: real people, real bots, and a real second machine should shape the next fleet refinements.
Run the first real multiplayer session
Move beyond synthetic fixtures and CI PaperMC checks with humans and bots sharing a persistent world under normal load.
TRACK THE PLAYTEST →Validate a second-machine connection
Exercise the documented authenticated LAN path in the same session, while keeping loopback-first defaults intact.
CHECK THE LAN GATE →Fold playtest findings into fleet UX
Use real usage to tune waypoint ergonomics, corridor defaults, and least-queue assignment quality instead of guessing.
FOLLOW THE FEEDBACK LOOP →A SIGNAL FOR EVERY BOT
The same lime-and-magenta language carries from the command core to the smallest event: clear ownership, visible state, and room to act.
FEATURES
WHAT YOU GET
39
MCP tools
Join, move, mine, build, craft, fight, chat, manage inventory, and coordinate a bot fleet.
⚑
Fleet coordination
Read every bot, auto-assign gather/build work, reserve known mutations, and route named waypoints without duplicate effort.
MCP
Any agent that speaks it
Claude, OpenClaw/DaVinci, or your own client over Streamable HTTP.
⛏
Bedrock + Java crossplay
Humans on phone, console or PC join the same world via Geyser, alongside the bots.
$_
One-command install
A single script brings up Java 21, PaperMC, Geyser, systemd units — or run it all in Docker.
◱
Live dashboard
Watch readiness, bot state, and a bounded chat-event stream that can replay safely after reconnect.
⇄
Chat bridge
Stream Minecraft chat to Discord or Telegram by default, with a secure inbound relay for your own integrations.
⌖
Named waypoints
Register shared targets once, send bots there with default corridor admission, and remove them cleanly.
LIVE /api/events
REPLAY WINDOW 256
284MinerAfound oak_log near base
285BuilderBotblueprint queue complete
286GuardBotzombie cleared at waypoint
Bearer-authenticated SSE with bounded replay, heartbeat checks, and an explicit reset when a client must reconcile.
FROM CLONE TO FIRST MCP CALL
OreMind stays on your machine, binds to loopback by default, and generates a bearer token during installation. These four steps complete the path from install to a verified client connection.
Install OreMind
Connect to an existing Java server with Docker. Add --full-stack if you need PaperMC and Geyser too.
git clone https://github.com/christopherdeck/oremind.git cd oremind bash scripts/install-linux.sh
Retrieve the token
Docker installers save the generated credential in .env. Bare-metal installs use /etc/default/minecraft-bot-mcp.
grep '^MCP_AUTH_TOKEN=' .env
Connect your MCP client
Clients that accept URL-and-header configuration can use this shape. The exact settings file varies by client.
{
"mcpServers": {
"oremind": {
"url": "http://127.0.0.1:3100/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
Verify before acting
Wait for readiness — not just process liveness — then call minecraft_bots from your MCP client before issuing actions.
curl -s http://127.0.0.1:3100/ready \ -H "Authorization: Bearer YOUR_TOKEN"
DASHBOARD
WATCH YOUR BOTS THINK
Illustrative dashboard preview showing the position, health, task, and guard-state telemetry exposed by OreMind.
MCPTestBot
pos 112, 64, -38
health 20 · food 18
task: gather(oak_log)
health 20 · food 18
task: gather(oak_log)
BuilderBot
pos 98, 70, 12
health 20 · food 20
task: build(blueprint)
health 20 · food 20
task: build(blueprint)
GuardBot
pos 100, 64, 0
guard mode: ON
last: attacked zombie
guard mode: ON
last: attacked zombie
BUILT TO RUN, NOT JUST DEMO
Ready means joined
/health confirms the HTTP process is alive. /ready stays unavailable until the configured bot has actually spawned in Minecraft.
Work stays bounded
Per-bot queues default to 256 steps, script batches stop at 128, and overflow is rejected atomically instead of silently overloading a bot.
Fleet conflicts are explicit
Known gather/build and reserved movement collisions return FLEET_RESERVATION_CONFLICT, while exhausted auto-assignment returns FLEET_NO_ELIGIBLE_BOT.
Events recover, not flood
/api/events keeps a bounded replay window for chat consumers. A missed cursor returns an explicit reset, so the bridge reconciles through /api/status instead of replaying stale history.
BEFORE YOU DEPLOY
Do I need a new Minecraft server?
No. The recommended Docker install connects OreMind to an existing Java server or a single-player world opened to LAN. The full-stack option can add PaperMC, Geyser, and Floodgate when you are starting from scratch.
Can Bedrock players join?
Yes. Bots connect as Java clients through Mineflayer, while Geyser and Floodgate let Bedrock players join the same world from phones, consoles, and Windows.
Is it safe to expose port 3100?
Do not expose it directly. OreMind binds to loopback by default; for remote access, keep bearer authentication enabled and use an SSH tunnel or authenticated TLS reverse proxy with an explicit origin allowlist.
Which AI clients work?
Any client that supports MCP Streamable HTTP and lets you send an Authorization header can connect. Client-specific configuration filenames vary.