Skip to main content
Glama

mcbaratone

A safety-gated autonomous Minecraft agent built around observable effects, resumable state, and explicit failure boundaries.

CI License: MIT Python 3.10+ Java 25

mcbaratone combines a Python controller, a Java/Fabric bridge, MCP and JSON-RPC interfaces, checkpointed planning, and evidence-driven tests. Its long-term goal is a no-cheat agent that can begin in a real Survival world, establish a sustainable base, reach and defeat the Ender Dragon, and continue into construction and terraforming without player intervention.

The complete spawn-to-endgame mission is not yet proven. The repository deliberately distinguishes implemented behavior, offline contract proof, bridge compilation, and observed in-world acceptance.

Why this project exists

Game automation makes distributed-systems failures unusually visible: a command can be accepted while the world never changes, a retry can duplicate an irreversible action, and a checkpoint can describe state that no longer exists. mcbaratone treats those as engineering problems rather than scripting edge cases.

The project emphasizes:

  • observed postconditions instead of command-success claims;

  • bounded retries and reconciliation for uncertain mutations;

  • resumable phase and objective state;

  • survival, identity, and world-safety gates;

  • transport-independent command and event contracts;

  • deterministic offline tests before any live-world exercise;

  • telemetry that separates dispatch, bridge response, completion, world effect, and durable progress.

Related MCP server: Minecraft MCP Server Pro

Architecture

flowchart LR
    P[Checkpointed planner] --> C[Python controller]
    C --> S[Safety and survival gates]
    S --> T[Transport abstraction]
    T -->|TCP / WebSocket / MCP| B[Java Fabric bridge]
    B --> R[Baritone + Minecraft]
    R --> E[Events and observations]
    E --> V[Postcondition verification]
    V --> P
    V --> O[Telemetry and dashboard]

See Architecture for the component and evidence boundaries.

Repository map

Path

Purpose

src/baritone_client/

Python transports, controller, state machines, safety logic, operations, MCP server, and HTTP API

bridge/

Java 25 Fabric bridge, command handlers, mutation ledger, event services, and bridge tests

tests/

Offline unit, contract, state-machine, recovery, and safety tests

tests/functional/

Explicitly selected live-world harnesses with destructive/read-only classifications

dashboard/

React/Vite operational dashboard frontend

actions/

Small reusable action facade

scripts/operations/

Bounded worker entry points retained as public examples

Verification snapshot

The publication candidate was validated on 12 September 2026:

  • Python: 2,338 passed, 1 skipped using the offline-default Pytest configuration;

  • secrets: complete retained Git history scanned with Gitleaks 8.30.1, 0 findings;

  • history: 627 commits retained after removing private operations material;

  • live-world tests remain excluded from the default Pytest command.

CI repeats the Python suite on Linux and Windows, builds and tests the Java bridge, and lints/builds the dashboard.

Quick start: offline development

python -m venv .venv

On Windows:

.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest -q

On Linux or macOS:

.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q

The default Pytest configuration excludes tests marked live_readonly and live_mutating.

Build the bridge

The bridge targets Minecraft 26.2 and requires Java 25. Its pinned Baritone Fabric API dependency, exact upstream source reference, hash, and LGPL-3.0 notice are documented under bridge/libs/.

Set-Location bridge
.\gradlew.bat --no-daemon --console=plain build

On Linux or macOS, use ./gradlew --no-daemon --console=plain build.

The bridge has no authentication layer. Keep it on loopback or another explicitly trusted transport; do not expose it directly to the internet.

Functional-test safety

Functional tests connect to Minecraft and are not interchangeable with offline tests. Some suites teleport players, grant items, alter blocks, or reset disposable worlds. Read the functional test safety guide, list the available tests, and select one explicit test ID. Never run an unfiltered live suite against a valued world.

.\.venv\Scripts\python.exe tests\functional\run_tests.py --list

Public/private boundary

This public repository intentionally excludes deployment inventories, server addresses, current handoffs, world maps, checkpoints, telemetry captures, family-server configuration, and recovery state. Those are operational data, not source dependencies.

That boundary is part of the design: public core development should remain reproducible without access to a specific server or world.

Status

Implemented and exercised offline:

  • TCP, WebSocket, HTTP, and MCP-facing integration surfaces;

  • checkpointed autonomous phases and adaptive scheduling;

  • navigation, inventory, crafting, storage, combat, farming, and construction policies;

  • postcondition verification and uncertain-mutation reconciliation;

  • event correlation, mutation ledger, circuit breaker, and telemetry components;

  • React dashboard and Java/Fabric bridge builds.

Still requiring end-to-end evidence:

  • a complete organic no-cheat spawn-to-Ender-Dragon run;

  • durable post-dragon construction and terraforming over long runtimes;

  • recovery across every real-world crash and partial-mutation boundary.

License and trademarks

First-party source is available under the MIT License. Bundled third-party components retain their own licenses; see Third-party notices.

Minecraft is a trademark of Microsoft. Baritone is an independent open-source project. mcbaratone is not affiliated with or endorsed by Microsoft, Mojang Studios, or the Baritone maintainers.

Available Tools

69 tools
axisC

Go to an axis or diagonal axis.

Inputs: no named parameters. Returns: result

batch_commandC

Execute multiple Baritone commands sequentially with proper error handling.

Inputs: commands (required), stop_on_error. Returns: result

blacklistB

Blacklist the closest block so Baritone won't attempt to get to it.

Inputs: no named parameters. Returns: result

broadcast_mission_stateC

Broadcast mission state update to all subscribed MCP clients.

Inputs: mission_data (required), priority. Returns: result

build_open_schematicB

Build the schematic that is currently open in Schematica.

Inputs: no named parameters. Returns: result

build_schematicC

Build a schematic. Optionally specify origin coordinates.

Inputs: x (required), y (required), z (required), name (required). Returns: result

cache_blockC

Cache block state information.

Inputs: x (required), y (required), z (required), block_state (required). Returns: result

cancel_commandB

Cancel the active Baritone task.

Inputs: no named parameters. Returns: result

cancel_uploadD

Cancel an upload.

Inputs: name (required). Returns: result

clear_cacheB

Clear all cached data.

Inputs: no named parameters. Returns: result

clear_goalB

Clear the current pathing goal.

Inputs: no named parameters. Returns: result

clickC

Click the destination on the screen (where player is looking).

Inputs: no named parameters. Returns: result

comeB

Tell Baritone to head towards your camera.

Inputs: no named parameters. Returns: result

damnD

daniel

Inputs: no named parameters. Returns: result

etaB

Get information about the estimated time until the next segment and the goal.

Inputs: no named parameters. Returns: result

exploreC

Explore the world from the origin of x,z (or player feet if omitted).

Inputs: x (required), z (required). Returns: result

farmC

Automatically harvest, replant, or bone meal crops.

Inputs: range (required), waypoint (required). Returns: result

findC

Search through Baritone's cache and attempt to find the location of the block.

Inputs: block_type (required). Returns: result

follow_entityB

Follow entities of a specific type (e.g. 'pig', 'cow').

Inputs: entity_type (required). Returns: result

follow_playerC

Follow a specific player.

Inputs: player_name (required). Returns: result

gcB

Call System.gc() to free up memory.

Inputs: no named parameters. Returns: result

get_cached_blockC

Get cached block information at coordinates.

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

get_command_analyticsC

Get performance analytics for a specific command.

Inputs: command_name (required). Returns: result

get_modified_settingsA

See all settings that have been modified from their default values.

Inputs: no named parameters. Returns: result

get_rate_limit_infoB

Get current rate limiting information.

Inputs: no named parameters. Returns: result

get_system_health_alertsA

Get current system health alerts and warnings.

Inputs: no named parameters. Returns: result

get_upload_progressC

Get progress of an upload.

Inputs: name (required). Returns: result

goal_coordinatesC

Set a goal to the specified coordinates. Provide at least one coordinate.

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

goto_block_typeC

Go to a block of a specific type (e.g. 'diamond_ore', 'portal', 'ender_chest').

Inputs: block_type (required). Returns: result

help_commandC

Get help for Baritone commands.

Inputs: query (required). Returns: result

inspect_build_siteB

Inspect a build site candidate by radius before any mutation.

Inputs: radius (required). Returns: result

invertA

Invert the current goal and path (run away from goal).

Inputs: no named parameters. Returns: result

minecraft_describe_toolC

Return stable guidance metadata for the selected MCP tool.

Inputs: name (required). Returns: result

minecraft_helpC

Return static, read-only guidance for MCP agents.

Inputs: task, topic. Returns: result

mine_quantityC

Mine a specific quantity of a block type.

Inputs: quantity (required), block_type (required). Returns: result

mission_checkpointC

Persist the active phase/checkpoint on the bridge.

Inputs: phase (required), note. Returns: result

mission_macroC

Invoke a mission macro or consume the queued macros (dequeue=True).

Inputs: name (required), params, dequeue. Returns: result

mission_queueC

Queue mission macros that the bridge should execute sequentially.

Inputs: actions (required), clear. Returns: result

pathC

Start pathing to the current goal.

Inputs: no named parameters. Returns: result

poll_eventsC

Poll events from the EventManager buffer.

Inputs: max_events, event_types. Returns: result

preview_build_planB

Generate a deterministic build-plan preview without bridge connection.

Inputs: build_plan (required). Returns: result

procB

View miscellaneous information about the process currently controlling Baritone.

Inputs: no named parameters. Returns: result

read_fileC

Read the contents of a file.

Inputs: file_path (required). Returns: result

reload_allB

Reload Baritone's world cache.

Inputs: no named parameters. Returns: result

renderC

Fix glitched chunk rendering.

Inputs: no named parameters. Returns: result

repackB

Re-cache the chunks around you.

Inputs: no named parameters. Returns: result

reset_all_settingsB

Reset all settings to their default values.

Inputs: no named parameters. Returns: result

reset_settingC

Reset a specific setting to its default value.

Inputs: name (required). Returns: result

run_commandC

Execute a raw Baritone/mission command string.

Inputs: command (required). Returns: result

save_allC

Save Baritone's world cache.

Inputs: no named parameters. Returns: result

set_goal_blockB

Apply a block-level navigation goal using goto command (bridge doesn't support GoalBlock).

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

set_settingC

Set a Baritone setting. For booleans, the value is option (toggles if omitted in chat, but here we require value).

Inputs: name (required), value (required). Returns: result

snapshotC

Return a combined snapshot of bridge telemetry.

Inputs: include_state, include_mission, include_inventory. Returns: result

start_miningC

Start the mining process for a given target block.

Inputs: target_block (required), quantity. Returns: result

start_schematic_uploadC

Start uploading a schematic file.

Inputs: name (required), expected_size (required), priority. Returns: result

stop_miningB

Stop the mining process.

Inputs: no named parameters. Returns: result

subscribe_eventsC

Subscribe to real-time event streaming for specified event types.

Inputs: event_types (required), priority_threshold. Returns: result

subscribe_mission_updatesC

Subscribe to real-time mission state updates and collaborative mission events.

Inputs: priority_threshold. Returns: result

surfaceC

Head towards the closest surface-like area.

Inputs: no named parameters. Returns: result

thiswayB

Go in the direction you are facing for a specified number of blocks.

Inputs: blocks (required). Returns: result

tunnelC

Dig a tunnel with specified dimensions.

Inputs: depth (required), width (required), height (required). Returns: result

unsubscribe_eventsC

Unsubscribe from real-time event streaming for specified event types.

Inputs: event_types (required). Returns: result

unsubscribe_mission_updatesB

Unsubscribe from real-time mission state updates.

Inputs: no named parameters. Returns: result

versionA

Get the version of Baritone.

Inputs: no named parameters. Returns: result

wp_deleteC

Delete a waypoint by name.

Inputs: name (required). Returns: result

wp_goalC

Set a goal to a waypoint.

Inputs: name (required). Returns: result

wp_listC

List waypoints with a specific tag.

Inputs: tag (required). Returns: result

wp_saveB

Save a waypoint. Uses current position if coordinates are not provided.

Inputs: x (required), y (required), z (required), name (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.3/5.0

    Scored across 69 tools

    Disambiguation2/5

    Many tools overlap in purpose: run_command/batch_command/mission_macro/mission_queue for execution, and numerous pathing/exploration variants (path, goal_coordinates, goto_block_type, come, thisway, axis, surface, explore). Several legacy commands (proc, eta, find, gc, damn) have vague descriptions, making it hard for an agent to choose reliably.

    Naming Consistency2/5

    Names mix single-word Baritone commands (find, path, explore, invert, damn) with snake_case verb_noun tools (set_goal_block, subscribe_events, wp_save). No consistent pattern is applied across the set; prefixes like wp_, mission_, and get_ are not used systematically.

    Tool Count1/5

    69 tools is extreme for this surface; many are niche legacy commands or redundant wrappers, far exceeding a well-scoped 3-15 tool set. The count creates a high cognitive load and increases misselection risk.

    Completeness4/5

    The set broadly covers pathing, mining, building schematics, waypoints, settings, cache, events, uploads, and command execution, suggesting fairly complete coverage for Baritone automation. Minor gaps and oddities remain, such as the non-functional 'damn' tool and some lifecycle operations being implicit via run_command.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers