Maicraft

Maicraft is an MCP server built to automatically interact with Minecraft using a Mineflayer-based bot. It lets you connect to a local or remote Minecraft server, drive a bot to explore, build, and perform scripted actions, and it integrates with MaiBot projects. You can run Maicraft in simple or advanced modes, with flexible configuration and tooling to test and debug your bot interactions.

How to use

You can operate Maicraft from a local MCP client by running a stdio-based server that connects to your Minecraft server. The client supports command line options and a configuration file, letting you tailor host, port, username, and authentication mode. Use this to drive the bot to perform actions such as moving, mining, crafting, and interacting with items or blocks. You can also enable a debugging log level to help diagnose issues during development and experimentation.

How to install

Prerequisites: you need Node.js (version 18 or newer) and a package manager such as npm, pnpm, or npx. A Python installation is required for building certain dependencies.

Option 1: Run Maicraft using npx with the latest release. This is the simplest approach and does not require a local build.

Option 2: Install Maicraft globally so the launcher reuses your local package instead of downloading on every start.

Option 3: Build Maicraft locally from source for environments with limited network access or when you need to modify the code. After building, run the local dist entry point.

Additional configuration and startup notes

Maicraft supports two primary configuration approaches: command line arguments for quick setups and a configuration file for complex scenarios. The command line is recommended for straightforward connections. A configuration file is ideal when you want repeatable setups and to manage many settings in one place.

When you start Maicraft, you will see startup logs, including the location of log files and a WebSocket endpoint for live logs if you enable it. Use the WebSocket stream to monitor events in real time from a UI or tooling.

Logging and debugging tips

Maicraft can emit logs to the console, to log files, and over WebSocket. If you need real-time insight while debugging, enable the WebSocket log stream and connect with a UI client to view logs as events occur.

For rapid debugging, you can launch the inspector tool in a dedicated development flow, either against a running Maicraft instance or against the source to experiment with actions and inputs. Use the inspector to run commands and observe bot behavior interactively.

Troubleshooting quick tips

If you encounter authentication or connection issues, verify the host and port, ensure the Minecraft server is reachable, and confirm the authentication mode matches your server configuration (offline, mojang, or microsoft). If log output is too verbose, tune the log level to reduce noise and help identify the root cause.

Available tools

chat

Send a chat message to the server.

basic_control

Perform basic game control actions such as move, jump, sneak, look_at, sleep, wake, and stop actions.

use_item

Use or activate an item held in hand or in the world (with optional targets).

move

Move to a coordinates, block, player, or entity target with configurable distance and timeout.

follow_player

Follow a specified player at a given distance for a duration.

swim_to_land

Swim toward the nearest land within a maximum distance.

mine_block

Mine a specified type of block with optional direction and distance.

place_block

Place a block at a specified location with optional facing.

craft_item

Craft a specified item in the current crafting context.

start_smelting

Start smelting a material in a furnace without waiting for completion.

collect_smelted_items

Collect items smelted in a furnace, optionally filtering by item type.

use_furnace

Interact with a furnace-like container to put, take, or view items.

smelt_item

Deprecated: smelt items in a furnace; recommended to use start_smelting + collect_smelted_items instead.

use_chest

Interact with nearby chests to store or withdraw items.

kill_mob

Attack and kill a specific mob by name.

follow_boss

Follow a boss mob (example placeholder for future expansion).