Minecraft MCP Server

How to use

Connect your MCP client to the local server you run, then issue high-level commands to the bot through the available tools. You can observe the bot’s position, health, and nearby entities, and you can guide the bot to move, look at coordinates, interact with the environment, and communicate with other players. Use the tools to navigate the world, manipulate blocks, manage inventory, and interact with players. Start by ensuring the server is running locally on port 25565 and that your client can reach localhost:25565. From there you can drive the bot to perform tasks such as exploring regions, collecting items, or following a player across the map.

How to install

{
  "mcpServers": {
    "mcp_minecraft": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-minecraft@latest",
        "--server-jar",
        "/absolute/path/to/minecraft-server/server.jar"
      ]
    }
  }
}

Prerequisites you need before installing: Node.js 18 or higher, Java 21.0.5 (recommended), Minecraft Launcher, Claude Desktop App, and macOS/Linux environment (Windows compatibility is not guaranteed). Close games with the F3+P shortcut to prevent the Minecraft process from pausing when Claude loses focus. If Claude restarts while the server is running, you may need to resolve lingering Java processes during the next launch.

Notes on installation and configuration

Quick Install (recommended) lets you set up the MCP integration in one command. Run this from your terminal:

npx -y @smithery/cli install mcp-minecraft --client claude

Alternatively, you can configure the MCP server manually by editing your Claude configuration file and adding the MCP server entry. The configuration path is a JSON file under your Claude support directory. Paste the following snippet, replacing the server jar path with the actual location on your system.

Troubleshooting and logs

If you encounter MCP connection issues after starting Claude or restarting Claude, look for lingering Java processes and terminate them, then restart the system if needed. The common steps are to force-quit Java processes on macOS/Linux or use the Task Manager on Windows. If the problem persists, a fresh reboot often clears lingering processes.

Server startup problems commonly involve verifying that Java is installed, the server.jar path is correct, and port 25565 is available. If you cannot connect, confirm the server is running and that you are using localhost as the server address. Check firewall rules if connections are blocked.

Find server logs in the minecraft-server directory and Claude Desktop logs in your user directory under Claude MCP-related logs. Reviewing these logs helps identify startup or connection issues quickly.

Configuration and environment

The MCP server is configured to run locally and exposes a set of tools and resources to control the in-game bot. The default bot username is MCPBot, and the server runs offline for local development with a default port of 25565 and 2 GB of memory allocated.

chat

Send chat messages to the server to communicate with players or the bot.

jump

Make the bot jump in place or while moving.

moveForward

Move the bot forward by stepping in the current facing direction.

moveBack

Move the bot backward to retreat or adjust position.

turnLeft

Rotate the bot to the left.

turnRight

Rotate the bot to the right.

placeBlock

Place a block at specified coordinates in the world.

digBlock

Break a block at specified coordinates and collect the item.

getBlockInfo

Query information about a block at specific coordinates.

selectSlot

Select a hotbar slot by index (0-8) to equip or use an item.

getInventory

Retrieve the bot's current inventory contents.

equipItem

Equip an item by name to a specified destination (hand, armor slot, etc.).

getStatus

Get the bot's current status, including health, hunger, and position.

getNearbyEntities

Return a list of nearby entities within a defined range.

attack

Attack a nearby entity by name or ID.

useItem

Use or activate the currently held item.

stopUsingItem

Stop using or deactivate the current item.

lookAt

Make the bot look at a specific set of coordinates.

followPlayer

Follow a specified player in the world.

stopFollowing

Stop following the current target.

goToPosition

Navigate the bot to specific world coordinates.