Skip to main content

AMP - Agentic Minecraft Player

AMP is a Python Minecraft bot with guided and autonomous planning modes. It connects directly to a Minecraft Java Edition server, implements the network protocol over raw TCP, builds live world state from chunk and entity packets, and converts natural-language goals into validated gameplay actions.

AMP 1.0 supports Minecraft Java Edition 26.1, 26.1.1, 26.1.2, and 26.2 on direct servers running in offline mode. Each advertised version has generated protocol data, fixture coverage, and live gameplay verification. Historical protocol implementations are available only through Git history.

Java version Protocol family Offline suite Live gameplay
26.1 Java 26.1 Verified Verified
26.1.1 Java 26.1 Verified Verified
26.1.2 Java 26.1 Verified Verified
26.2 Java 26.2 Verified Verified

Install

AMP requires Python 3.10 or later.

python -m pip install amp-mc

This installs the amp and amp-world commands. Contributors can use python -m pip install -e ".[dev]" for an editable development install. The exact environment used to validate the release is recorded in requirements-lock.txt.

Copy .env.example to .env and configure a model provider. Shell, CI, and deployment environment variables take precedence over .env.

Anthropic is the default:

AMP_MODEL_PROVIDER=anthropic
ANTHROPIC_API_KEY=your-api-key
# ANTHROPIC_MODEL=claude-opus-4-6

An OpenAI-compatible /chat/completions endpoint can be used instead:

AMP_MODEL_PROVIDER=openai-compatible
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=your-model-name
# OPENAI_API_KEY=optional-for-local-servers

This path supports local servers such as Ollama, LM Studio, and vLLM without an API key. Remote endpoints must use HTTPS; HTTP is accepted only for loopback development servers.

Run

Start AMP with:

amp

To run AMP in a copy of an existing single-player world without Microsoft authentication, use the documented local-world workflow. One Python command prepares and starts the server, grants optional operator access, connects AMP in the selected planning mode, and coordinates shutdown. The human player joins the printed local server address manually.

The CLI collects the server host, port, username, Minecraft version, and gameplay mode before connecting. It defaults to the latest supported release, Java 26.2.

  • Guided mode accepts 1 instruction at a time, plans it, and waits for the next instruction.
  • Autonomous mode accepts a high-level goal and replans after each action batch for up to 20 steps. New instructions can be injected while it runs.

Survival and creative are the supported gameplay modes.

Implemented gameplay

  • A* pathfinding over loaded chunk data, including flat movement, 1-block steps, and 1-block drops
  • Tick-paced movement along path edges, airborne step trajectories, idle gravity, landing detection, and cancellation after server position corrections
  • Position, health, food, chunks, block updates, player inventory, selected hotbar slot, and nearby entity tracking
  • Creative and survival mining with inventory tool selection and hardness-based timing
  • Inventory-aware block placement with support-face selection
  • Attacks against tracked entities already within reach
  • Guided and autonomous model planning with validated command objects
  • Server-confirmed mining and placement results returned to the autonomous loop
  • Connection recovery, keepalive handling, bounded packet frames, and bounded decompression

Current limits

  • Microsoft-authenticated online-mode servers and Java Realms are disabled in AMP 1.0. The implementation is retained, but Minecraft Services rejects newly registered client IDs unless Microsoft approves them. See Authentication status.
  • World decoding and navigation target the standard Java 26 Overworld height range.
  • Crafting, container interaction, and general inventory management are not implemented.
  • Blueprint import, material planning, and multi-block construction are not implemented.
  • Paths use discrete 1-block edges, expanded into tick-paced position updates. AMP does not model horizontal acceleration or momentum, sprint, swim, climb, jump gaps, open doors, bridge gaps, or continuously replan around moving obstacles.
  • A single-hit attack requires a target already within reach. A repeated kill action can approach and re-path to a tracked, reachable target, but AMP does not discover targets outside its loaded entity state or check line of sight.
  • Mining timing does not account for enchantments, status effects, or underwater and airborne penalties.
  • Real-provider behavior remains a manual pre-release gate; the offline suite uses injected provider fakes.

The complete post-1.0 roadmap is maintained in Future work.

Architecture

amp/cli.py             interactive setup and mode selection
amp/bot.py             public facade and dependency composition
amp/connection.py      TCP framing, compression, encryption, and keepalive
amp/java26_protocol.py Java 26 login, decoding, and action encoding
amp/world_state.py     live world, inventory, and entity state
amp/gameplay.py        movement, mining, placement, and combat coordination
amp/movement.py        tick-paced path movement, gravity, and landing
amp/lifecycle.py       connection recovery and worker lifecycle
amp/chunk.py           chunk, NBT, palette, and block-state decoding
amp/pathfinder.py      A* pathfinding over loaded world data
amp/execution.py       action queue, protocol dispatch, and result confirmation
amp/planner.py         provider-neutral guided and autonomous planning
amp/model_clients.py   model-client contract and provider adapters
amp/command_data.py    planner and executor action validation

The planner receives a bounded world snapshot and returns JSON command objects. amp/command_data.py validates model output. amp/bot.py sends navigation and gameplay actions to amp/gameplay.py, including a three-dimensional search for the nearest reachable block to mine. amp/execution.py serializes the resulting actions and waits for observable world-state changes where confirmation is available.

Provider-specific API shapes stay in amp/model_clients.py. The Anthropic adapter uses the official Anthropic Python SDK. The OpenAI-compatible adapter follows the OpenAI-compatible Chat Completions message and response shape using Python's standard library.

Tests

Install the development dependencies and run the offline suite:

python -m pip install -r requirements-dev.txt
python -m pytest

The live connection test skips automatically when no server is listening on localhost:25565. Dedicated Java 26 checks cover movement, creative mining, survival mining, inventory handling, placement, and combat against a local offline-mode server with RCON enabled. The complete matrix has been run for every version listed above.

See Testing for the commands and test boundaries.

Generated Minecraft data

AMP checks in compact protocol, block, item, and entity registries generated from a pinned PrismarineJS/minecraft-data revision. Running AMP does not require Node.js, network access, or the upstream dataset.

Regenerate and verify the data with:

python tools/sync_minecraft_data.py
python tools/sync_minecraft_data.py --check
python -m pytest

See Third-party notices for attribution and licensing details.

AMP itself is available under the MIT License.

Project documents

Metadata

Release files for amp-mc 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for amp-mc 1.0.0
File Size Uploaded Provenance Actions
amp_mc-1.0.0.tar.gz 452.2 kB With provenance Details for amp_mc-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amp-mc 1.0.0
File Interpreter ABI Platform Actions
amp_mc-1.0.0-py3-none-any.whl Python 3 none any Details for amp_mc-1.0.0-py3-none-any.whl

Total release size: 838.4 kB

Release files / amp_mc-1.0.0.tar.gz

Download URL amp_mc-1.0.0.tar.gz
Size 452.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ca80fb04591c9ee54b05d8866c2cc90a5aea82d8fe2d87dfd0a0cac6e04ca380
BLAKE2b-256 checksum
How to use checksums
d65e7f1a458c7088c1187f25ce6da5c688e9b723c941cf3982e8080eda21349a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 31, 2026.

Transparency log

Release files / amp_mc-1.0.0-py3-none-any.whl

Download URL amp_mc-1.0.0-py3-none-any.whl
Size 386.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b2b254da791974a7b4fbf2cbfa7d4439d40c27cb06a846e1b32b7427b81b4f66
BLAKE2b-256 checksum
How to use checksums
6aa729175c535223179cea0f676b79a31572b9d611a8367e5366db034549ba14
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 31, 2026.

Transparency log

Security for amp-mc 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for amp_mc-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 31, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page