DEV Community

Failed Ahmad
Failed Ahmad

Posted on

minecraft-mcp-server: Giving AI Agents a Body Inside Minecraft

#mcp #minecraft #ai #typescript

What is this?

minecraft-mcp-server is a Model Context Protocol server that puts an AI agent inside a real Minecraft Java Edition world through mineflayer. It exposes 61 tools covering movement, building, mining, combat, farming, inventory, villager trading, and world perception — so any MCP-compatible client can spawn a bot that actually sees the world, walks around it, and acts on it.

This isn't tied to any single AI product. It speaks plain MCP over stdio, so it works with any MCP host — Claude Desktop, Claude Code, Cursor, Cline, Windsurf, your own custom MCP client, or anything else that can launch a local MCP server. If your agent can talk MCP, it can play Minecraft.

Built for singleplayer worlds opened via "Open to LAN," offline-mode/cracked servers (e.g. TLauncher), and standard online-mode servers.

Tool chest — what your agent can do

Category Tools
🔌 Connection connect, disconnect, status
👀 Perception position, nearby blocks, block lookup, find block, nearby entities, inventory
🚶 Movement goto position, goto player, follow player, look at, look direction, stop, jump
🧱 Building place block, dig block, build cuboid structure, clear area
🖐️ Interaction chat, equip item, toss item, craft item, attack entity, activate block, eat, sleep, collect block (mine + auto-pickup)
🎒 Inventory open/deposit/withdraw/close container, use furnace, give item (creative), move item slot
⚔️ Combat sprint, sneak, use held item (block/draw/drink), shoot bow
🌾 Farming till soil, plant seed, harvest crop
🌍 World biome lookup, light level, get time, read sign
🗣️ Social whisper, list players, open villager trades, execute trade
🎲 Misc mount, dismount, respawn, wait

Every tool returns structured JSON and actionable error messages — no raw stack traces dumped on your agent.

Installation 

git clone https://github.com/AhmadTariq1337/minecraft-mcp-server.git
cd minecraft-mcp-server
npm install
npm run build
Enter fullscreen mode Exit fullscreen mode

This compiles TypeScript into dist/index.js — the entry point your MCP host will launch.

Configuring your MCP client 

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/absolute/path/to/minecraft-mcp-server/dist/index.js"]
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

No API keys, no cloud dependency — everything runs locally over stdio.

Quick start in-game

  1. Open your Minecraft world (singleplayer works great).
  2. Press Escape → Open to LAN — note the port number shown in chat.
  3. Ask your agent to connect: "Connect to localhost on port <port> as <bot-name>, auth offline."
  4. That's it — your agent can now see the world, move, mine, build, and chat.

Version support

This rides on mineflayer, which determines actual protocol support. At time of writing, it supports up through Minecraft 1.21.x. Mojang's newer year.drop versioning isn't yet supported upstream — older clients like OptiFine 1.21.11 or vanilla 1.21.x work out of the box.

Links

Top comments (0)