MCP Minecraft Remote
This project is inspired by mcp-minecraft by arjunkmrm. While the original only supported local Minecraft server connections, this project was newly created from scratch to add support for connecting to remote Minecraft servers.
Minecraft Remote Control using MCP (Model Context Protocol).
Features
- Connect to and control a Minecraft player via an AI assistant
- Navigate, mine, build, and interact with the Minecraft world
- Chat with other players on the server
- Check inventory, player position, and server information
- Advanced movement control including jumping, sneaking, and sprinting
- Entity interaction including attacking and following
- Container usage (chests, furnaces, etc.)
- Item crafting and villager trading
- Detailed inventory management
Installation
Installing via Smithery
To install Minecraft Remote Control for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @nacal/mcp-minecraft-remote --client claude
Quick Install (Recommended)
npx -y @smithery/cli install mcp-minecraft-remote --client claude
Follow the CLI prompts to complete the setup.
Manual Installation
# Install from npm
npm install -g mcp-minecraft-remote
# Or clone the repository
git clone https://github.com/nacal/mcp-minecraft-remote.git
cd mcp-minecraft-remote
# Install dependencies
npm install
# Build the project
npm run build
Usage
Using with Claude Desktop
-
Navigate to Claude Desktop configuration file:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
- Windows:
-
Add the Minecraft Remote MCP configuration to your configuration file:
{
"mcpServers": {
"minecraft-remote": {
"command": "npx",
"args": ["-y", "mcp-minecraft-remote@latest"]
}
}
}
If you've installed it globally:
{
"mcpServers": {
"minecraft-remote": {
"command": "mcp-minecraft-remote"
}
}
}
If you've cloned the repository locally:
{
"mcpServers": {
"minecraft-remote": {
"command": "node",
"args": ["/absolute/path/to/mcp-minecraft-remote/build/index.js"]
}
}
}
- Save the file and restart Claude Desktop
- Start a new conversation with Claude and begin using the Minecraft control commands
Important Server Requirements
- Server Online Mode: The Minecraft server must have
online-mode=falseset in the server.properties file. This allows the bot to connect without authentication against Minecraft's session servers. - If using a server with authentication, you'll need to provide valid premium account credentials when connecting.
Available Tools
Core Functionality
connectToServer: Connect to a Minecraft server with specified credentialsdisconnectFromServer: Disconnect from the Minecraft serversendChat: Send a chat message to the servergetServerInfo: Get information about the connected server
Movement
getPosition: Get current player positionmoveTo: Move to specific coordinatesmoveControl: Basic movement controls (forward, back, left, right, jump, sprint, sneak, stop)lookAt: Make the player look in a specific direction or at coordinates
World Interaction
digBlock: Mine a block at specific coordinatesplaceBlock: Place a block at specific coordinates
Inventory Management
checkInventory: Basic inventory checkinventoryDetails: Get detailed information about inventory itemsequipItem: Equip an item from inventory to hand or armor slottossItem: Throw items from inventory
Entity Interaction
getNearbyPlayers: Get list of nearby playersgetNearbyEntities: Get a list of all entities nearbyattackEntity: Attack a specific entityuseOnEntity: Use held item on a specific entityfollowEntity: Follow a specific entity
Container Interaction
openContainer: Open a container (chest, furnace, etc.) at specific coordinateswithdrawItem: Take items from an open containerdepositItem: Put items into an open containercloseContainer: Close the currently open container
Crafting
getRecipes: Get a list of available crafting recipescraftItem: Craft an item using available materials
Trading
listTrades: List available trades from a nearby villagertradeWithVillager: Trade with a nearby villager
Example Prompts
Basic Controls
- "Connect to the Minecraft server at play.example.com with the username player1"
- "What is my current position in the game?"
- "Move me to coordinates x=100, y=64, z=-200"
- "Make me walk forward for 3 seconds"
- "Make me jump and sprint toward that mountain"
Inventory & Items
- "Check what's in my inventory in detail"
- "Equip my diamond sword to my hand"
- "Throw 5 dirt blocks from my inventory"
Block Interaction
- "Dig the block at coordinates x=10, y=65, z=20"
- "Place a stone block at coordinates x=11, y=65, z=20"
Entity Interaction
- "Are there any other players nearby?"
- "What entities are within 20 blocks of me?"
- "Attack the zombie with ID 12345"
- "Follow the player named Steve"
Container Usage
- "Open the chest at coordinates x=100, y=64, z=200"
- "Take 10 iron ingots from the chest"
- "Put 5 cobblestone in the chest"
- "Close the container"
Crafting & Trading
- "What recipes do I have available for a wooden pickaxe?"
- "Craft 4 sticks using the wood in my inventory"
- "Check what trades the nearby villager offers"
- "Trade with the villager to get 10 emeralds"
Communication
- "Send a hello message to the chat"
- "Tell everyone that I found diamonds"
Requirements
- Node.js 18+
- An AI assistant that supports MCP (like Claude)
- A Minecraft Java Edition server (version 1.8 or later)
Note: This tool has been tested and verified to work specifically with vanilla Minecraft 1.21. While it may function with other versions or modded servers, compatibility is not guaranteed.
License
MIT