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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.