Minecraft MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Minecraft MCP Server Find the nearest iron ore and mine it for me."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Minecraft MCP Server
⚠️ CLAUDE DESKTOP DUAL LAUNCH WARNING: Claude Desktop may sometimes launch MCP servers twice (known issue), which can lead to incorrect behavior of this MCP server. If you experience issues, restart Claude Desktop application to fix the problem. Alternatively, consider using other MCP clients.
https://github.com/user-attachments/assets/6f17f329-3991-4bc7-badd-7cde9aacb92f
A Minecraft bot powered by large language models and Mineflayer API. This bot uses the Model Context Protocol (MCP) to enable Claude and other supported models to control a Minecraft character.
Prerequisites
Git
Node.js
A running Minecraft game (the setup below was tested with Minecraft 1.21.8 Java Edition included in Microsoft Game Pass)
An MCP-compatible client. Claude Desktop will be used as an example, but other MCP clients are also supported
Related MCP server: Maicraft
Getting started
This bot is designed to be used with Claude Desktop through the Model Context Protocol (MCP).
Run Minecraft
Create a singleplayer world and open it to LAN (ESC -> Open to LAN). Bot will try to connect using port 25565 and hostname localhost. These parameters could be configured in claude_desktop_config.json on a next step.
MCP Configuration
Make sure that Claude Desktop is installed. Open File -> Settings -> Developer -> Edit Config. It should open installation directory. Find file with a name claude_desktop_config.json and insert the following code:
{
"mcpServers": {
"minecraft": {
"command": "npx",
"args": [
"-y",
"github:yuniko-software/minecraft-mcp-server",
"--host",
"localhost",
"--port",
"25565",
"--username",
"ClaudeBot"
]
}
}
}Double-check that right --port and --host parameters were used. Make sure to completely reboot the Claude Desktop application (should be closed in OS tray).
Running
Make sure Minecraft game is running and the world is opened to LAN. Then start Claude Desktop application and the bot should join the game.
It could take some time for Claude Desktop to boot the MCP server. The marker that the server has booted successfully:
You can give bot any commands through any active Claude Desktop chat. You can also upload images of buildings and ask bot to build them 😁
Don't forget to mention that bot should do something in Minecraft in your prompt. Because saying this is a trigger to run MCP server. It will ask for your permissions.
Using Claude 4.0 Sonnet could give you some interesting results. The bot-agent would be really smart 🫡
Example usage: shared Claude chat
Available Commands
The authoritative tool list (names, descriptions, parameters) is whatever your MCP client shows after connecting; tools are registered in src/bot.ts (see the register*Tools functions). Rough map:
Observation:
look-around(one-call snapshot: position, health, inventory, adjacent blocks, entities),show-adjacent-blocks,get-position,get-status,get-nearby-block-types,find-blocks-by-type,get-block-info/get-blocks-infoMovement:
move-horizontally, stairs up/down (move-horizontally-and-up/down-using-steps),dig-directly-down,move-up-by-pillaring,swim-horizontally,jump-over-obstacle,center-in-blockMining/building:
dig-adjacent-blocks,place-block. Mining tools take anallowMiningOftool-to-blocks map — an explicit allowlist so the bot never mines something you didn't intendCrafting/smelting:
craft-item,smelt-item(loads the furnace and returns; smelting continues in game time),furnace-check(progress + collect output)Containers:
chest-peek,chest-deposit,chest-withdrawInventory/items:
list-inventory,find-item,equip-item,drop-item,eat-food,activate-itemEntities:
find-entity,attack-entity,entity-interact,entity-mount/entity-dismount,villager-open/villager-tradeCommunication:
send-chat,read-chat,player-whisperMisc:
bed-sleep/bed-wake,fish,block-activate,sign-update,detect-gamemode
Viewing Logs
The bot writes detailed logs to logs/minecraft.log in JSON format. This includes bot state changes, game events, and debug information.
View all logs
cat logs/minecraft.logFilter by log level
# View only errors
grep '"level":"error"' logs/minecraft.log
# View warnings (including bot state changes like oxygen/health drops)
grep '"level":"warn"' logs/minecraft.log
# View info messages
grep '"level":"info"' logs/minecraft.logFilter by event type (using jq)
# Install jq if needed: brew install jq (macOS) or apt-get install jq (Linux)
# View game events (chat, deaths, spawns)
jq 'select(.type=="game_event")' logs/minecraft.log
# View bot state changes (oxygen, health, durability)
jq 'select(.type=="bot_state")' logs/minecraft.log
# View tool calls
jq 'select(.type=="tool_call")' logs/minecraft.log
# View only errors with full details
jq 'select(.level=="error")' logs/minecraft.logDevelopment Setup
git clone https://github.com/hibukki/minecraft-mcp-server.git
cd minecraft-mcp-server
pnpm install
pnpm run build
pnpm test
pnpm run lintContributing
This application was made in just two days, and the code is really simple and straightforward. All refactoring commits, functional and test contributions, issues and discussion are greatly appreciated!
Feel free to submit pull requests or open issues for improvements. Some areas that could use enhancement:
Additional documentation
More robust error handling
Tests for different components
New functionality and commands
To get started with contributing, please see CONTRIBUTING.md.
Available Tools
53 toolsactivate-itemA
Use currently held item (e.g., shoot bow, raise shield, throw snowball, drink potion)
Inputs: offhand.
attack-entityA
Attack a nearby entity repeatedly until it dies
Inputs: type, maxDistance.
bed-sleepA
Sleep in a bed to skip night and set spawn point
Inputs: x (required), y (required), z (required).
bed-wakeB
Wake up from bed
Inputs: no named parameters.
block-activateB
Activate a block (button, lever, door, trapdoor, etc.)
Inputs: x (required), y (required), z (required).
center-in-blockA
Center the bot in both X and Z axes within the current block
Inputs: no named parameters.
chest-depositB
Put items from the inventory into a chest
Inputs: x (required), y (required), z (required), count (required), +1 more.
chest-peekA
Look at the contents of a chest at the specified position
Inputs: x (required), y (required), z (required).
chest-withdrawB
Take items from a chest into the inventory
Inputs: x (required), y (required), z (required), count (required), +1 more.
craft-itemB
Craft an item using available materials
Inputs: itemName (required), useCraftingTable (required), count.
detect-gamemodeB
Detect the gamemode on game
Inputs: no named parameters.
dig-adjacent-blocksC
Dig multiple blocks sequentially
Inputs: positions (required), timeoutSeconds, allowedMiningToolsToMinedBlocks.
dig-directly-downA
Dig straight down by mining blocks directly below the bot. Good if the target is far down.
Inputs: allowMiningOf (required), digTimeout, blocksToDigDown.
drop-itemC
Drop items from inventory
Inputs: itemName (required), count.
eat-foodA
Consume food to restore hunger
Inputs: itemName.
elytra-flyB
Activate elytra flight
Inputs: no named parameters.
entity-dismountA
Dismount from current mount
Inputs: no named parameters.
entity-interactC
Right-click/interact with nearest entity
Inputs: entityType, maxDistance.
entity-mountB
Mount a horse, boat, minecart, etc.
Inputs: entityType (required), maxDistance.
entity-use-item-onA
Use held item on entity (shears on sheep, dye on wolf, etc.)
Inputs: entityType (required), maxDistance.
equip-itemC
Equip a specific item
Inputs: itemName (required), destination.
find-blocks-by-typeB
Find blocks of a specific type (sorted by distance, closest first)
Inputs: blockType (required), maxResults, maxDistance.
find-entityB
Find the nearest entity of a specific type
Inputs: type, maxDistance.
find-itemB
Find a specific item in the bot's inventory
Inputs: nameOrType (required).
fishA
Start fishing (requires fishing rod equipped)
Inputs: no named parameters.
furnace-checkA
Check furnace state (input/fuel/output/progress) and collect any smelted output into the inventory
Inputs: x, y, z.
get-block-infoB
Get information about a block at the specified position
Inputs: x (required), y (required), z (required).
get-blocks-infoA
Get information about multiple blocks at specified positions
Inputs: positions (required).
get-nearby-block-typesA
Get all unique block types and entity types in the nearby area with counts and closest distance
Inputs: maxBlockTypes, maxDistanceUpDown, maxDistanceSideways.
get-positionA
Get the current position of the bot
Inputs: no named parameters.
get-statusA
Get the bot's health, food, and other status information
Inputs: no named parameters.
jump-in-placeB
Make the bot jump
Inputs: no named parameters.
jump-over-obstacleA
Jump over a small obstacle ahead of the bot in the direction toward target. Good for obstacles of height 1 (blocking the bot's feet but not head)
Inputs: targetX (required), targetY (required), targetZ (required).
list-inventoryA
List all items in the bot's inventory
Inputs: no named parameters.
look-aroundA
Get a full situational snapshot in one call: position, health/food, held item, inventory summary, time of day, nearby entities, and all adjacent blocks. Good first call after spawning or when unsure what's going on.
Inputs: no named parameters.
look-atB
Make the bot look at a specific position
Inputs: x (required), y (required), z (required).
move-horizontallyA
Move the bot toward a target block that is more or less the same height (Y) as the bot. Doesn't dig down (for a low Y target), doesn't build up (for a high Y target), so bad for those
Inputs: targetX (required), targetY (required), targetZ (required).
move-horizontally-and-down-using-stepsC
Mine down multiple steps. Good for going vertically and down at the same time wile mining.
Inputs: nextStepPos (required), allowMiningOf (required), stepsToGoDown (required), digTimeout.
move-horizontally-and-up-using-stepsC
Mine up multiple steps. Good for going forwards-and-up.
Inputs: nextStepPos (required), stepsToGoUp (required), allowMiningOf (required), digTimeout.
move-horizontally-by-miningA
Mines blocks ahead and walks forward, repeating for the specified number of blocks to make progress underground
Inputs: targetX (required), targetY (required), targetZ (required), allowMiningOf (required), +2 more.
move-up-by-pillaringB
Build a pillar by jumping and placing blocks below. Good for trying to go way up.
Inputs: height (required), allowMiningOf.
place-blockB
Place a block at the specified position
Inputs: x (required), y (required), z (required), blockName (required).
player-whisperB
Send a private message to a player
Inputs: message (required), username (required).
read-chatA
Get recent chat messages from players
Inputs: count.
send-chatB
Send a chat message in-game
Inputs: message (required).
show-adjacent-blocksA
Show all blocks directly adjacent to the bot in all horizontal directions and at all height levels (above head, head height, feet height, below feet). The bot is 2 blocks tall. Good first call when stuck.
Inputs: no named parameters.
sign-updateC
Update text on a sign
Inputs: x (required), y (required), z (required), text (required), +1 more.
smelt-itemA
Load a furnace with items and fuel and start smelting. Returns once the furnace is lit; use furnace-check later to see progress and collect the output.
Inputs: itemName (required), count, fuelName.
swim-horizontallyA
Swim horizontally toward a target position. Enables jump/swim-up and moves forward in a loop, stopping forward movement when target is reached or overshot. Keeps jump enabled at the end in case still in water.
Inputs: targetX (required), targetY (required), targetZ (required).
toggle-swim-up-jump-upA
Toggle the bot's jump state on or off. When underwater, holding jump makes the bot swim upward. Use this to control swimming or jumping state.
Inputs: enabled (required).
villager-openA
Open trade window with nearest villager
Inputs: maxDistance.
villager-tradeB
Execute a trade with an open villager
Inputs: tradeIndex (required), times.
write-bookB
Write content to a book and quill
Inputs: slot (required), pages (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 53 tools
While many tools are clearly distinct, there are overlapping concepts such as 'look-around' which duplicates 'get-status' and 'show-adjacent-blocks', and multiple movement/breaking tools with similar functions. However, descriptions are detailed enough to differentiate primary use cases.
All tool names follow a consistent lowercase verb-noun pattern, with hyphens separating words. Compound names like 'move-horizontally-by-mining' and 'toggle-swim-up-jump-up' are still readable and maintain the convention.
With 53 tools, the server is far beyond the typical well-scoped range. Even for a complex game like Minecraft, this is an extreme number and appears to be a collection of every possible action rather than a curated set.
The tool set covers a broad range of Minecraft mechanics: movement, mining, building, chests, entities, villagers, trading, sleeping, fishing, elytra, chat, and status. There are no obvious missing major operations for typical gameplay.
Maintenance
Related MCP Connectors
All 20 YourAITools agent APIs in one MCP server. Most tools free; pay with credits or x402.
MCP server for AI dialogue using various LLM models via AceDataCloud
Connect AI agents to Flato's editable canvas runtime through a hosted MCP server.
Generate AI video, images and audio, and browse your history, from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to control a Minecraft bot through natural language commands using the Mineflayer library. Provides intelligent pathfinding, chat communication, entity detection, and generic access to Minecraft bot capabilities.ISC
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to play and interact with Minecraft servers through mineflayer, providing automated actions like mining, movement, crafting, and real-time game event monitoring.17 npm8MIT
- FlicenseNot gradedqualityBmaintenanceEnables natural language control of a Minecraft bot, allowing it to execute tasks like mining, exploring, and item management via AI-powered commands.3-
- AlicenseAqualityCmaintenanceEnables AI agents to control a Minecraft bot inside a Java Edition world via MCP, providing tools for movement, building, mining, combat, farming, trading, inventory, and world perception.5596 npm1MIT