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
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.
170 AUTOMATED TESTS
Current Node test suite: 168 passing and 2 explicit environment-specific skips.
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
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.
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.