Skip to main content
Glama

Minecraft Agent Body

Give an AI agent a bounded, inspectable body in Minecraft Java Edition.

This project is deliberately model-neutral. It does not contain an LLM, an API key, a Discord bot, or JNAIQ. Instead, it exposes one Mineflayer-controlled Minecraft player through:

  • MCP over stdio for Claude, Codex, and other MCP hosts.

  • A loopback-only JSON adapter for JNAIQ, Discord bots, and custom agent loops.

The model remains the decision-maker. The body reports observations and executes named actions.

Current status

Implemented and locally tested without Minecraft: configuration validation, event cursors, in-band tool failures, MCP startup, loopback-only HTTP transport, and package checks.

Requires your live environment to validate: joining your server, Microsoft device-code login, pathfinding, mining, crafting, placing, combat, eating, and sleeping. Minecraft protocol support follows Mineflayer's supported versions.

Related MCP server: Minecraft MCP Server Pro

Requirements

  • Node.js 20 or newer

  • A Minecraft Java server you are allowed to join

  • For online-mode servers, a Microsoft account that owns Minecraft Java Edition

  • An MCP host or a custom program that can call the JSON adapter

Install

git clone https://github.com/several-dozen-lizards/minecraft-agent-body.git
cd minecraft-agent-body
npm install
npm test

Copy .env.example to .env if your launcher loads environment files, or set the variables in the MCP host configuration. The program does not parse .env by itself so secrets stay under the control of the host that launches it.

Fast local test

Start a local Minecraft Java server in offline mode, then:

npm run start:http

In another terminal:

curl http://127.0.0.1:31822/health
curl -X POST http://127.0.0.1:31822/call -H "Content-Type: application/json" -d '{"name":"minecraft_connect","arguments":{}}'
curl -X POST http://127.0.0.1:31822/call -H "Content-Type: application/json" -d '{"name":"minecraft_status","arguments":{}}'

PowerShell equivalents are in docs/QUICKSTART_WINDOWS.md.

Tools

The first public cut includes:

minecraft_connect, minecraft_disconnect, minecraft_status, minecraft_inventory, minecraft_events, minecraft_look, minecraft_goto, minecraft_follow, minecraft_stop, minecraft_collect, minecraft_dig, minecraft_place, minecraft_craft, minecraft_equip, minecraft_eat, minecraft_sleep, minecraft_attack, and minecraft_say.

minecraft_say refuses messages beginning with /. This prevents the chat tool from silently becoming a server-operator console.

Connect a brain

Design promises

  • The core has no provider SDK and no model preference.

  • Credentials are read from the launching environment and never returned by a tool.

  • The JSON adapter refuses non-loopback binds.

  • Long actions do not silently stack; a second action receives BUSY until the current action finishes or minecraft_stop is called.

  • Optional coordinate bounds constrain movement and world mutation.

  • Every action returns structured success or a structured, actionable error.

  • Events and action receipts can be consumed incrementally by cursor.

Not the same as the 141-hour visual benchmark

That experiment had the model operate ordinary keyboard and mouse controls from visual observations. This project gives the agent a structured Minecraft body, which is more reliable and dramatically cheaper to run. A later optional visual module can add screenshots without making them the only sense available.

License

MIT. Minecraft is a trademark of Microsoft/Mojang; this independent project is not affiliated with or endorsed by them.

Available Tools

18 tools
minecraft_attackA

Approach and strike one nearby visible entity by name.

Inputs: target (required).

minecraft_collectC

Find and dig one or more nearby blocks by block name.

Inputs: block (required), count, maxDistance.

minecraft_connectC

Connect the body to its configured Minecraft Java server.

Inputs: auth, host, port, version, +1 more.

minecraft_craftA

Craft an item using current inventory and a nearby crafting table when needed.

Inputs: item (required), count.

minecraft_digC

Dig the block at an exact coordinate.

Inputs: x (required), y (required), z (required).

minecraft_disconnectA

Disconnect from Minecraft.

Inputs: no named parameters.

minecraft_eatA

Eat the most nourishing recognized food in inventory.

Inputs: no named parameters.

minecraft_equipC

Equip an inventory item.

Inputs: item (required), destination.

minecraft_eventsA

Read recent world and action events after a cursor.

Inputs: limit, cursor.

minecraft_followA

Continuously follow a visible player until stopped.

Inputs: player (required), distance.

minecraft_gotoC

Walk near a world coordinate.

Inputs: x (required), y (required), z (required), range.

minecraft_inventoryB

List inventory item names, counts, and slots.

Inputs: no named parameters.

minecraft_lookA

Set absolute yaw and pitch in radians.

Inputs: yaw (required), pitch (required).

minecraft_placeC

Place an inventory block at a coordinate against a neighboring face.

Inputs: x (required), y (required), z (required), item (required), +1 more.

minecraft_sayA

Send plain Minecraft chat. Slash commands are refused.

Inputs: message (required).

minecraft_sleepA

Find and sleep in a nearby bed.

Inputs: no named parameters.

minecraft_statusA

Observe health, position, weather, gaze target, and nearby entities.

Inputs: no named parameters.

minecraft_stopA

Immediately stop navigation and held movement controls.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 18 tools

    Disambiguation4/5

    Each tool targets a distinct action or observation, but minecraft_collect and minecraft_dig overlap somewhat in block-digging behavior. The descriptions clarify coordinate-based digging versus nearby block collection, so an agent can generally select correctly.

    Naming Consistency4/5

    All tools share the consistent minecraft_ prefix and use lowercase snake_case, which is predictable. Minor deviation is that some names are nouns (status, inventory, events) rather than verbs, but this does not cause real confusion.

    Tool Count4/5

    18 tools is slightly above the ideal range, but each tool covers a meaningful body capability like movement, inventory, combat, or world interaction. The count feels appropriate for a Minecraft agent that needs both observation and action.

    Completeness4/5

    The tool surface covers connection, status, movement, block manipulation, inventory, crafting, eating, sleeping, attacking, and chat. Obvious gaps include dropping items, using non-food items, and interacting with entities or containers, but core agent workflows are not blocked.

    Maintenance

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables controlling an autonomous Minecraft Java Edition player through MCP, with structured world perception, navigation, gathering, crafting, combat, building, skill-based task execution, and long-term memory integration.
      -