nacal 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).

• 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

To install Minecraft Remote Control for Claude Desktop automatically via Smithery:

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

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

Follow the CLI prompts to complete the setup.

# 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

1. 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

2. 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"]
    }
  }
}

1. Save the file and restart Claude Desktop
2. Start a new conversation with Claude and begin using the Minecraft control commands

• Server Online Mode: The Minecraft server must have online-mode=false set 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.

• connectToServer: Connect to a Minecraft server with specified credentials
• disconnectFromServer: Disconnect from the Minecraft server
• sendChat: Send a chat message to the server
• getServerInfo: Get information about the connected server

• getPosition: Get current player position
• moveTo: Move to specific coordinates
• moveControl: Basic movement controls (forward, back, left, right, jump, sprint, sneak, stop)
• lookAt: Make the player look in a specific direction or at coordinates

• digBlock: Mine a block at specific coordinates
• placeBlock: Place a block at specific coordinates

• checkInventory: Basic inventory check
• inventoryDetails: Get detailed information about inventory items
• equipItem: Equip an item from inventory to hand or armor slot
• tossItem: Throw items from inventory

• getNearbyPlayers: Get list of nearby players
• getNearbyEntities: Get a list of all entities nearby
• attackEntity: Attack a specific entity
• useOnEntity: Use held item on a specific entity
• followEntity: Follow a specific entity

• openContainer: Open a container (chest, furnace, etc.) at specific coordinates
• withdrawItem: Take items from an open container
• depositItem: Put items into an open container
• closeContainer: Close the currently open container

• getRecipes: Get a list of available crafting recipes
• craftItem: Craft an item using available materials

• listTrades: List available trades from a nearby villager
• tradeWithVillager: Trade with a nearby villager

• "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"

• "Check what's in my inventory in detail"
• "Equip my diamond sword to my hand"
• "Throw 5 dirt blocks from my inventory"

• "Dig the block at coordinates x=10, y=65, z=20"
• "Place a stone block at coordinates x=11, y=65, z=20"

• "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"

• "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"

• "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"

• "Send a hello message to the chat"
• "Tell everyone that I found diamonds"

• 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.

MIT