Connects the bot to a running Minecraft Java Edition world (server, LAN world, or local server jar).

For TLauncher: TLauncher accounts are typically NOT Microsoft-authenticated, so use auth="offline" (this is also correct for cracked/offline-mode servers and singleplayer worlds opened via "Open to LAN"). Use auth="microsoft" only for a real Mojang/Microsoft account joining an online-mode server.

To connect to your own singleplayer world: open the world in Minecraft, press Escape -> "Open to LAN", note the port shown in chat, then call this tool with host="localhost" (or "127.0.0.1") and that port.

Must be called before any other minecraft_* tool.

Returns: { message: string } confirming connection and spawn position. Errors: connection refused, wrong port, version mismatch, or auth-mode mismatch (offline bot hitting an online-mode server, or vice versa).

Cleanly disconnects the bot from the current world/server. Safe to call even if not connected.

Returns the bot's current health, hunger, position, gamemode, dimension, in-game time, weather, XP, and who else is online.

Returns: { connected: boolean, username: string, health: number (0-20), food: number (0-20), position: { x, y, z }, yaw: number, pitch: number, gameMode: string, dimension: string, isDay: boolean, isRaining: boolean, experienceLevel: number, heldItem: string | null, onlinePlayers: string[] }

Call minecraft_connect first if this returns connected: false.

Returns the bot's exact current coordinates, facing direction, and which block it's standing on/in.

Returns: { x, y, z, yaw, pitch, standingOn: string, dimension: string }

Scans the world around the bot and lists non-air blocks it can see, closest first. This is the bot's "eyes" for terrain/structures — use it before building or navigating.

Args:

• radius (number, 1-32): how far to scan, in blocks (default 8)

• block_names (string[], optional): only return blocks matching these exact Minecraft block ids (e.g. ["oak_log", "stone", "chest"]). Omit to return all non-air blocks.

Returns: { count: number, blocks: [{ x, y, z, name }] } capped at 400 results.

Looks up a single block at exact world coordinates.

Returns: { x, y, z, name, hardness: number | null, diggable: boolean } or an error if the chunk isn't loaded.

Searches outward from the bot for the nearest block(s) matching a given block name — useful for "find me some water" / "find diamond ore" before navigating or mining.

Returns: { found: boolean, count: number, blocks: [{ x, y, z, name, distance }] }

Lists players, mobs, and other entities near the bot, closest first — the bot's awareness of who/what is around it.

Args:

• radius (number, 1-64): search radius in blocks (default 16)

• type_filter (string, optional): one of "player", "hostile", "mob" (non-hostile mobs/animals), "all" (default "all")

Returns: { count: number, entities: [{ id, type, name, username?, x, y, z, distance }] }

Returns everything the bot is carrying: hotbar/inventory items, currently held item, and worn armor.

Returns: { items: [{ slot, name, count, displayName }], heldItem: string | null, armor: { head, torso, legs, feet } (each string | null) }

Places one block from the bot's inventory at the given world coordinates. Automatically walks within reach first and finds a solid neighboring block to place against. The target coordinates must currently be empty (air) and adjacent to at least one solid block — you can't place a block floating in mid-air.

Returns: { message: string } Errors: item not in inventory, no solid neighbor to place against, or unreachable.

Mines/breaks the block at the given coordinates. Automatically walks within reach first. Drops fall to the ground — use minecraft_collect_block instead if you also want the bot to auto-pick-up the drops.

Returns: { message: string, block: string } Errors: block not diggable (e.g. bedrock, air), unreachable, or missing required tool.

Fills a cuboid region between two corner coordinates with a block from inventory — for walls, floors, platforms, boxes. Builds bottom-up so each block has something to rest against.

Args:

• hollow (boolean): if true, only builds the outer shell (walls/floor/ceiling) instead of a solid block. Good for rooms.

• Region is capped at 500 blocks total; oversized requests are truncated.

Returns: { placed, skipped, failed, message }. Blocks that already match are skipped; blocks with no solid neighbor available yet are reported as failed rather than aborting the whole build.

Digs out (breaks) every non-air, diggable block in a cuboid region between two corners — for clearing land or hollowing out a room. Digs top-down.

Region is capped at 500 blocks total.

Returns: { dug: number, skipped: number, message: string }

Sends a message in in-game chat, visible to all players on the server. Also works for chat commands if the message starts with '/' and the bot has permission.

Equips an item from inventory to the bot's hand or an armor slot.

Returns: { message: string } Errors: item not found in inventory.

Drops item(s) from inventory onto the ground in front of the bot.

Returns: { message: string }

Crafts an item using a recipe the bot currently has ingredients for. If the recipe needs a 3x3 grid, pass use_crafting_table=true and make sure a crafting table is within a few blocks (minecraft_find_block "crafting_table", or minecraft_place_block one first).

Returns: { message: string, crafted: string, count: number } Errors: unknown item, no known recipe fits current inventory, or no crafting table in reach when one is required.

Attacks a specific entity by id (from minecraft_get_nearby_entities), or the nearest hostile mob if no id is given. Swings the bot's currently equipped weapon once — call repeatedly for multiple hits.

Returns: { message: string, target: string } Errors: entity not found / out of reach, or no hostile mobs nearby (when entity_id omitted).

Right-clicks a block at the given coordinates — opens chests/doors/trapdoors/furnaces, presses buttons, pulls levers, opens the crafting-table UI, etc. Walks within reach first.

Returns: { message: string, block: string } Errors: no block there, or unreachable.

Equips a food item from inventory and eats it to restore hunger.

Returns: { message: string } Errors: item not found, item isn't food, or the bot can't eat right now (food already full).

Finds the nearest bed (or one at given coordinates) and sleeps in it. Only works at night/during thunderstorms, and only if the bed is safe (no monsters nearby).

Returns: { message: string } Errors: no bed found nearby, not night, monsters nearby, or bed occupied/unsafe.

Finds the nearest matching block(s), mines them, and automatically walks over to pick up the drops — more convenient than minecraft_dig_block when you actually want the item in inventory (e.g. "get me some wood").

Returns: { message: string, requested: number } Errors: no matching blocks within range, or a dig/pickup failure partway through.

Paths the bot to a target position using pathfinding (navigates around obstacles, up stairs, across gaps it can jump). Blocking call — resolves once the bot arrives or pathfinding times out (60s).

Returns: { message: string, position: { x, y, z } } on arrival. Errors: unreachable destination, timeout, or no path found.

Paths the bot to stand near a named online player. Blocking call.

Returns: { message: string, position } on arrival. Errors: player not found/not loaded, or unreachable.

Starts (or stops) continuously following a named player at a set distance. Unlike minecraft_goto_player this does NOT block — the bot keeps following in the background until minecraft_stop is called or this tool is called again with stop=true.

Returns: { message: string }

Turns the bot's head/body to face a specific point. Purely cosmetic/aiming — doesn't move the bot. Useful before minecraft_attack_entity or minecraft_activate_block for precision.

Cancels any active pathfinding goal (goto/follow) and releases all movement keys. Use this to interrupt movement in progress.

Makes the bot jump once in place.

Opens a chest, trapped chest, barrel, shulker box, dispenser, or dropper at the given coordinates and lists its contents. Walks within reach first. The container stays open until minecraft_close_container is called — minecraft_container_deposit/withdraw act on whatever is currently open.

Returns: { message, containerType: string, items: [{ slot, name, count }] } Errors: no container block there, or unreachable.

Moves an item from the bot's inventory into the currently open container. Call minecraft_open_container first.

Returns: { message } Errors: no container open, or item not carried.

Moves an item from the currently open container into the bot's inventory. Call minecraft_open_container first.

Returns: { message } Errors: no container open, or item not present in the container.

Closes whatever container, furnace, or villager-trade UI is currently open. Safe to call even if nothing is open.

Opens a furnace (or blast furnace / smoker) at the given coordinates, loads input material and fuel from the bot's inventory, waits for smelting to progress, then collects whatever output is ready and closes the furnace. One call handles the whole loop.

Args:

• input_item: material to smelt, e.g. "raw_iron", "raw_beef", "sand"

• fuel_item: fuel to burn, e.g. "coal", "oak_planks". Omit if the furnace already has fuel loaded.

• count: how many items to smelt (default 1)

• wait_seconds: how long to wait before collecting output (default 12; vanilla smelting is ~10s/item with normal fuel). Call again to collect more once it's finished.

Returns: { message, collected: number, itemName: string | null } Errors: no furnace there, missing input/fuel in inventory, or unreachable.

Spawns an item stack directly into the bot's inventory. Only works while the bot is in creative gamemode.

Returns: { message } Errors: bot not in creative mode, unknown item id, or inventory full.

Moves an item stack from one inventory slot to another, for organizing the hotbar/inventory. Slot map: 0 crafting output, 1-4 crafting grid, 5-8 armor, 9-35 main inventory, 36-44 hotbar, 45 off-hand.

Returns: { message }

Turns sprinting on or off. Sprint state persists across movement until toggled off or the bot stops.

Turns sneaking (crouching) on or off — prevents falling off edges and hides the bot's nametag/hides it from some mobs.

Starts or stops "using" the currently equipped item — this is the generic right-click-and-hold action: raising a shield to block, drawing back a bow/crossbow, drinking a potion, using a fishing rod, blocking with a sword (1.9+), etc. Pair with minecraft_shoot_bow for a ready-made bow-firing flow, or call this directly for shields/potions.

Returns: { message }

Equips a bow, optionally aims at a target point, draws it back for charge_ms, then fires. A full draw (~1000ms+) does full damage; shorter draws do less.

Returns: { message } Errors: no bow in inventory.

Equips a hoe and tills the dirt/grass block at the given coordinates into farmland, ready for planting. Walks within reach first.

Returns: { message } Errors: no hoe in inventory, block isn't tillable, or already farmland.

Plants a seed item on farmland at the given coordinates (till it first with minecraft_till_soil). Works for any plantable item: seeds, carrots, potatoes, beetroot_seeds, melon/pumpkin seeds, nether_wart (on soul sand).

Returns: { message } Errors: target block isn't farmland/soul sand, space above is occupied, or seed not in inventory.

Breaks a fully-grown crop block at the given coordinates. For known crop types (wheat, carrots, potatoes, beetroots, nether_wart) this checks maturity first and refuses to harvest early unless force=true.

Returns: { message, block: string } Errors: nothing there, crop not fully grown (unless force=true), or not diggable.

Looks up the biome at exact world coordinates.

Returns: { x, y, z, biome: string | null }

Returns light levels at a block — useful for checking if an area is safe from mob spawns (block light < 8 with sky light 0 at night is generally spawnable).

Returns: { x, y, z, light: number (0-15, total), skyLight: number (0-15) }

Returns the current in-game time and weather.

Returns: { timeOfDay: number (0-24000 ticks), day: number, isDay: boolean, moonPhase: number (0-7), isRaining: boolean }

Turns the bot to face a compass direction (north/south/east/west) or straight up/down. Purely cosmetic/aiming — does not move the bot.

Reads the text written on a sign at the given coordinates.

Returns: { x, y, z, front: string, back: string | null }

Sends a private message to a specific player, visible only to them (uses the server's /msg or /tell equivalent).

Returns: { message: string }

Lists every player currently online, with ping and gamemode.

Returns: { count, players: [{ username, ping, gamemode }] }

Walks to and opens trade with a villager (by entity id from minecraft_get_nearby_entities, or the nearest one), and lists its available trades. Stays open until minecraft_close_container is called — use minecraft_trade to execute a trade.

Returns: { message, trades: [{ index, give: string[], receive: string, usesLeft, disabled }] } Errors: no villager nearby/found.

Executes a trade on the currently open villager (call minecraft_open_villager first) by trade index.

Returns: { message } Errors: no villager open, invalid trade index, trade disabled, or missing required items.

Mounts a rideable entity — boat, minecart, horse, donkey, mule, pig (with saddle), strider, or camel — by entity id (from minecraft_get_nearby_entities) or the nearest rideable one. Walks within reach first.

Returns: { message } Errors: no rideable entity found nearby.

Dismounts whatever entity/vehicle the bot is currently riding. Safe to call even if not mounted.

Respawns the bot at its spawn point/bed after dying. Only needed if the server's auto-respawn is disabled — check minecraft_status for health 0 first.

Pauses for a number of seconds — useful for letting things settle (smelting, mob spawning, water flowing) between other tool calls.