Server facts
Minecraft MCP Server
Project
- Author
- yuniko-software
- Website
- yuniko.software/mcp-server/
- License
- Apache-2.0
- Category
- Games & 3D
Tech
- Runtime / language
- node
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 782
- Last commit
- Data as of
Tags
- Building
- Game Bot
- Inventory
- Minecraft
- Mineflayer
Overview
Minecraft MCP Server lets Claude and other MCP-compatible assistants control a character in a running Minecraft game. It uses Mineflayer to translate assistant requests into actions such as moving to coordinates, looking at a location, jumping, and flying. Inventory tools let the assistant inspect carried items, locate a particular item, and equip it. Block operations cover placement, digging, nearby-block discovery, and inspection. Other commands support furnace smelting, nearby entity discovery, in-game chat, and game-mode detection. The README also describes asking the assistant to build from an uploaded image.
The documented setup opens a single-player world to the local network and launches the bot from an MCP client. Hostname, port, and bot username are passed as arguments, so the configuration needs to match the game connection. Git and Node.js 20.10.0 or later are listed prerequisites, together with a running game and an MCP-compatible client. The current compatibility notice names Minecraft 1.21.11 and warns that newer releases may fail, while the walkthrough says it was tested with Java Edition 1.21.8. Those are distinct statements rather than a promise of universal version support. Claude Desktop may take time to start the server, and the README recommends fully restarting the application after configuration changes. Prompts should explicitly identify Minecraft actions so the assistant invokes the game integration.
Install & configure
Requirements
- Git
- Node.js 20.10.0 or later
- A running compatible Minecraft game with a reachable world
- An MCP-compatible client
npx -y github:yuniko-software/minecraft-mcp-server --host localhost --port 25565 --username ClaudeBotThe README opens a single-player world to LAN and configures the bot's host and port to match. Its current support notice names Minecraft 1.21.11, while the setup walkthrough mentions testing Java Edition 1.21.8. Restart the desktop client fully after configuration. No required environment variables are stated.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"minecraft-mcp-server": {
"command": "npx",
"args": [
"-y",
"github:yuniko-software/minecraft-mcp-server",
"--host",
"localhost",
"--port",
"25565",
"--username",
"ClaudeBot"
],
"env": {}
}
}
}Config file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"minecraft-mcp-server": {
"command": "npx",
"args": [
"-y",
"github:yuniko-software/minecraft-mcp-server",
"--host",
"localhost",
"--port",
"25565",
"--username",
"ClaudeBot"
],
"env": {}
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
{
"servers": {
"minecraft-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"github:yuniko-software/minecraft-mcp-server",
"--host",
"localhost",
"--port",
"25565",
"--username",
"ClaudeBot"
],
"env": {}
}
}
}Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"minecraft-mcp-server": {
"command": "npx",
"args": [
"-y",
"github:yuniko-software/minecraft-mcp-server",
"--host",
"localhost",
"--port",
"25565",
"--username",
"ClaudeBot"
],
"env": {}
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"minecraft-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"github:yuniko-software/minecraft-mcp-server",
"--host",
"localhost",
"--port",
"25565",
"--username",
"ClaudeBot"
],
"env": {}
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| get-position | Read the bot's current coordinates. |
| move-to-position | Move the bot toward specified coordinates. |
| look-at | Aim the bot's view at a selected position. |
| jump | Make the bot perform a jump. |
| move-in-direction | Move in a chosen direction for a specified duration. |
| fly-to | Fly directly toward a target position. |
| list-inventory | Inspect items currently carried by the bot. |
| find-item | Locate a particular item in the bot's inventory. |
| equip-item | Equip a selected inventory item. |
| place-block | Place a block at a selected position. |
| dig-block | Dig the block at a selected position. |
| get-block-info | Inspect information about a block. |
| find-blocks | Locate nearby blocks of a requested type. |
| smelt-item | Process items using a furnace-like block. |
| find-entity | Locate the closest entity matching a requested type. |
| send-chat | Post a message to the game's chat. |
| read-chat | Read recent messages sent by players. |
| detect-gamemode | Determine the current game mode. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Direct an assistant-controlled character around a LAN world.
- Place and dig blocks during an assisted building session.
- Inspect inventory and equip items through natural-language requests.
- Read and send in-game messages while interacting with the world.
Strengths
- Covers movement, inventory, blocks, smelting, and chat.
- Allows configurable game host, port, and bot username.
- Works with MCP clients beyond the Claude Desktop example.
Limitations
- Requires a running game and a reachable world.
- The compatibility notice warns that versions newer than 1.21.11 may not work.
- Desktop client startup can take time.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
