Every bot is two things: a harness — everything it can do — and a
decision layer that picks what it does next.
This repo builds the harness by hand, in five steps, and then hands the decision
layer to an AI. By the end you can type “come find me” in Minecraft chat and a
bot works out where you are, walks there, and fights off whatever attacks you on
the way — without you writing a single line that parses that sentence.
snippets/
01-spawn.ts connect a bot to the server
02-pathfinder.ts send it somewhere — it routes around obstacles (A*)
03-follow.ts capability one: follow a player
04-protect.ts capability two: fight hostiles nearby
05-mcp.ts describe the harness to a model, and stop deciding
The first four are the harness. The fifth doesn’t add a single new ability — it
just describes what’s already there, and lets Claude choose.
About 15 minutes. You need Node.js, a Minecraft client, and a server to connect
to (either someone else’s, or your own — both covered below).
node --version
npm --version
You need Node 20.6 or newer — older versions can’t read the .env file.
TLauncher is a free launcher that works with
offline-mode servers.
Use 1.21.1. mineflayer only supports specific Minecraft versions, and your
client, your server and the bot library all have to agree. If you’re joining
someone else’s server, match whatever version they tell you.
Joining one? Skip to step 4 — you just need its address and port.
Running your own? See Running a local server at
the bottom, then come back. Your address will be localhost on port 25565.
git clone https://github.com/synacktraa/hacking-minecraft.git
cd hacking-minecraft
npm install
Then create your .env:
cp .env.example .env
and fill it in:
HOST=localhost
PORT=25565
BOT_NAME=ChangeMeBot
PLAYER_NAME=YourMinecraftUsername
PLAYER_NAMEis the username you picked in TLauncher. The bot uses it to
find you, so it must match exactly, including capitals.
BOT_NAMEis a name for your bot. If you’re sharing a server with other
people, make it unique — two bots with the same name get each other kicked.
There’s a script that writes the file for you if you prefer:
./snippets/set-config.sh <host> <port> <your-minecraft-username>
npm run check
This confirms the server is up and that mineflayer can actually speak its
Minecraft version — which is the failure that’s hardest to diagnose on your own.
Join the server in Minecraft, then run a snippet directly:
npx tsx --env-file=.env snippets/01-spawn.ts
Within a few seconds a second player appears next to you and says hello.
Ctrl+C stops it.
Work through the rest in order — each one adds a single capability:
npx tsx --env-file=.env snippets/02-pathfinder.ts # walks 20 blocks east, routing around obstacles
npx tsx --env-file=.env snippets/03-follow.ts # follows you
npx tsx --env-file=.env snippets/04-protect.ts # follows you and fights hostiles
For 04-protect.ts, run /time set night in Minecraft so something actually
turns up to fight.
--env-fileis not optional — without it the bot has no idea where to
connect. It needs Node 20.6+.
The last step connects Claude to the harness so it decides what the bot does.
Install Claude Code:
npm install -g @anthropic-ai/claude-code
Register the MCP server — run this from the repo root, so the absolute paths
are baked in and it works no matter where you start Claude:
claude mcp add minecraft -- npx tsx --env-file="$PWD/.env" "$PWD/snippets/05-mcp.ts"
claude mcp list
Now start claude and talk to it:
you — follow me, I’m YourUsername
bot — I can’t see you, you’re outside my view distance. What are your coordinates?
you — sure, I’m at 100 64 -200
It reads the coordinates out of that sentence and walks there. Nothing in
05-mcp.ts parses text — the tool descriptions do the work.
Only if you want your own server instead of joining someone else’s.
PaperMC needs Java 21 or newer.
java --version
PaperMC is a fast Minecraft server that’s easy to run.
java -Xms3G -Xmx3G -jar paper-1.21.1-XXX.jar --nogui
eula.txt and change eula=false to eula=true25565Match the version everywhere. Your PaperMC build, your TLauncher version
andnpm run checkall have to agree. 1.21.1 is a safe choice — it’s on
mineflayer’s tested list. If you pick something newer,npm run checkwill
tell you whether mineflayer can speak it.
TLauncher accounts aren’t Mojang accounts, so the server has to allow them. Open
server.properties and set:
online-mode=false
Then restart the server.
Only do this on a server you control and don’t expose to the internet —
offline mode means anyone can join as any username.
In Minecraft: Multiplayer → Add Server → address localhost:25565.
No data available for version X
The server is running a Minecraft version mineflayer doesn’t support. Run
npm run check — it names the newest version that works. Upgrading npm packages
won’t help; the support has to ship upstream first.
ECONNRESET, or the server looks offline
It may still be starting, or it rejected two rapid connection attempts. Wait ten
seconds and try again. npm run check retries automatically.
Bot connects, then immediately disconnects
Something else is using the same BOT_NAME. Change it in .env.
Bot connects but ignores you
PLAYER_NAME doesn’t match your in-game username. It’s case-sensitive.
The bot won’t follow you across a distance
That’s not a bug — it can only see players inside its view distance. That
limitation is the whole point of 05-mcp.ts.
Cannot find module 'mineflayer'
Run npm install in the repo root.