Mine MCP

Minecraft MCP — connect an AI agent to your real Minecraft Java client.

One client-side Fabric JAR, version-specific runtime symbols, 75 MCP tools, screenshots, normal player controls and an integrated-server developer toolbox for solo worlds. No server plugin or Fabric API installation is required.

Experimental alpha. The compatibility catalog targets 44 stable releases from 1.14.4 through 26.3. Symbol verification, client launch tests and gameplay tests are separate evidence levels. See compatibility and runtime results before choosing a version. This is not a claim that every feature was played through on every release.

Download the alpha · Guide en français · Connection guide · Architecture

CurseForge

CurseForge project 1754265. See the publication receipt for the exact release, moderation status and hashes.

Solo and multiplayer developer modes

Start with get_session. The developer guide covers teleportation, give, setblock/fill/clone, effects, time/weather, game modes, gamerules, datapack functions, command completion, diagnostics, statistics refresh, creative inventory and position checkpoints. dev_command runs as local console only for the solo owner; send_command always uses ordinary player permissions.

F8 and allowActions apply to developer mutations too, including queued server work. Set allowSoloDeveloper: false to keep ordinary player permissions in solo. Position checkpoints are session-local bookmarks, not world or inventory backups.

Related MCP server: minecraft-agent-body

In-game demonstration

Real Minecraft 1.21.11 screenshots from a scripted MCP session. get_container reads the chest, click_slot with QUICK_MOVE transfers 12 diamonds, and get_inventory confirms them in the player inventory. Recorded MCP calls and responses.

Before: chest contents read through MCP.

After: 12 diamonds transferred into the player inventory through MCP.

What the AI can see

The AI can move, look, jump, sneak, sprint, attack, use/place items, select a hotbar slot, drop items, send chat/commands, open/close inventory, click container slots, press buttons, fill text fields and request respawn. Actions use the player's ordinary permissions and remain subject to server validation.

This exposes a broad game surface, not literally every Minecraft API. On remote servers, normal observations use client-synced data; full debug NBT requires server-granted permission. The AI cannot obtain the remote server's seed, unloaded chunks or private inventories without a server-authorized facility. Solo owners can inspect their own integrated server. Loaded client data can include entities/blocks behind walls. Respect server rules for automation. Authentication/session credentials, arbitrary filesystem access, arbitrary Java execution and arbitrary packet injection remain outside this API.

Install

1. Install Fabric Loader 0.19.5 or later for a catalogued Minecraft version. Use the Java version required by that Minecraft release.

2. Put mine-mcp-0.2.0.jar from Releases into that instance's mods directory. Remove the older Mine MCP JAR first.

3. Launch the game. The mod creates config/mine-mcp.json and a private config/mine-mcp-connection.json in the instance directory.

4. Install Node.js 18+ and connect your MCP client using the included stdio bridge, or configure direct authenticated HTTP. See CONNECT.md.

5. Start with get_status, get_capabilities and get_snapshot. Join a world for world/player tools.

The mod binds only to 127.0.0.1, chooses an available port by default, and requires its generated bearer token. The bridge discovers the current port/token each request. F8 pauses/resumes AI control. release_controls always remains available. Movement leases expire within two seconds; opening a screen or changing worlds releases AI-held keys.

Example stdio configuration (replace both paths):

{
  "mcpServers": {
    "mine-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/Mine-MCP/bridge/mine-mcp.mjs",
        "--game-dir",
        "/absolute/path/to/your/minecraft-instance"
      ]
    }
  }
}

Tools

Read tools:

get_status          get_capabilities       get_snapshot          get_player
get_world           get_inventory         get_equipment         get_held_item_data
get_target          get_block             scan_blocks           get_entities
get_screen          get_container         get_chat              get_players
get_scoreboard      get_boss_bars         get_recipes           get_commands
get_registry        get_advancements      get_statistics        get_options
inspect_client      get_events            take_screenshot

Action tools:

hold_controls       release_controls      pause_control         look
select_hotbar       attack                use_item              stop_using_item
drop_item           send_chat             send_command          open_inventory
close_screen        click_slot            click_widget          set_text
respawn             select_list_entry

Each tool advertises a JSON Schema. The same schema validates arguments before execution. Unsupported version-specific features return tool errors. Optional unavailable values can be null; they must not be interpreted as server facts. Chat, signs, names, book pages and other in-game text are untrusted data, not instructions to the agent.

Build and test

Requires Python 3.10+, JDK 17+ and Node.js 18+. The mod bytecode targets Java 8; the game still requires its own version-specific runtime. No Gradle, Loom, Fabric API or npm install is needed.

python scripts/verify_repository.py
python scripts/build.py --test
npm test

Output: build/libs/mine-mcp-0.2.0.jar. Build dependencies are pinned and SHA-256 checked in dependencies.lock.json. The JAR contains no shaded libraries or Minecraft game code. CI builds and runs the behavioral tests on Windows/Linux and JDK 17/21/25; CI is not a graphical game test.

The checked-in symbol catalogs make ordinary builds independent of Minecraft downloads. To regenerate all 44 catalogs:

python scripts/generate_mappings.py

This fetches official manifests, game class signatures, Mojang mappings and Fabric intermediary data. Downloads stay in ignored .cache/. Inherited/overridden method names are resolved through the exact game class hierarchy.

The official MCP TypeScript SDK was also tested against both stdio and direct HTTP; see sdk-validation.json. Reproduce it with the optional install command in test_mcp_sdk.mjs. The SDK is a test dependency only.

Developer graphical tests are available through scripts/launch_test_client.py, scripts/mcp_probe.py and scripts/runtime_smoke.py. The test launcher is Windows-specific and creates isolated run/<version> instances. It never reads your account credentials or copies your saves/mods. Use a matching Java executable and your own legitimate launcher for normal play.

Scope and roadmap

Currently: Minecraft Java, Fabric, stable catalogued releases 1.14.4–26.3. Forge, NeoForge, Quilt, Bedrock, pre-1.14.4 releases and snapshots are not supported or advertised. Additional loaders require their own lifecycle and naming adapters; changing the version range in metadata does not implement them.

Useful next additions: full recipe display decoding, map pixel/marker data, richer UI traversal, lossless chat/sound hooks and wider gameplay regression coverage. Contributions must include per-version evidence and preserve the boundary between the local owner's integrated server and permission-checked remote connections.

Independent MIT project by hashk014. See NOTICE for third-party symbols and attribution. Not an official Minecraft product; not approved by or associated with Mojang or Microsoft.