🎮 Minecraft MCP Server

An MCP (Model Context Protocol) server that allows AI agents to play Minecraft! Built with Mineflayer and the official MCP TypeScript SDK.

🚀 Features

Connection Management

• Connect/disconnect to any Minecraft server
• Support for offline and Microsoft authentication
• Automatic version detection

Movement & Navigation

• Pathfinding: Navigate to any coordinates using A* pathfinding
• Follow players: Dynamically follow other players
• Look at: Point the bot's view at specific coordinates
• Jump: Make the bot jump

Block Interaction

• Dig blocks: Break blocks at specific coordinates
• Place blocks: Place blocks from inventory
• Find blocks: Search for specific block types nearby
• Activate blocks: Interact with chests, buttons, doors, etc.
• Collect blocks: Navigate to and mine specific blocks

Inventory Management

• View inventory: See all items in inventory
• Equip items: Equip items to hand, off-hand, or armor slots
• Drop items: Discard items from inventory

Crafting

• Craft items: Automatically craft items with available recipes
• Get recipes: Query available recipes for any item

Combat

• Attack entities: Attack mobs or players
• Stop attacking: Cease combat
• Get nearby entities: List all entities within range

Chat & Communication

• Send chat: Send public chat messages
• Whisper: Send private messages to players
• Get players: List all players on the server

Survival Features

• Auto-eat: Automatic food consumption when hungry
• Eat: Manually eat specific food items
• Sleep: Find and sleep in nearby beds
• Get status: Full status report (health, hunger, position, etc.)

📦 Installation

Quick Start (Recommended)

Run directly with npx - no installation required:

npx -y minecraft-ai-mcp

Global Installation

npm install -g minecraft-ai-mcp
minecraft-ai-mcp

From Source

# Clone the repository
git clone https://github.com/harjjotsinghh/minecraft-mcp.git
cd minecraft-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

🔧 Configuration

Claude Desktop Configuration

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": ["-y", "minecraft-ai-mcp"]
    }
  }
}

Cursor Configuration

Add to your .cursor/mcp.json file:

{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": ["-y", "minecraft-ai-mcp"]
    }
  }
}

Alternative: Using Global Installation

If you installed globally, you can use the command directly:

{
  "mcpServers": {
    "minecraft": {
      "command": "minecraft-ai-mcp"
    }
  }
}

🎯 Available Tools

Tool	Description
connect	Connect to a Minecraft server
disconnect	Disconnect from the server
get_status	Get bot's current status
goto	Navigate to coordinates
follow_player	Follow a specific player
stop_movement	Stop all movement
jump	Make the bot jump
look_at	Look at coordinates
dig_block	Break a block
place_block	Place a block
get_block_info	Get info about a block
find_blocks	Find nearby blocks
get_inventory	View inventory contents
equip_item	Equip an item
drop_item	Drop items
craft_item	Craft an item
get_recipes	Get crafting recipes
attack_entity	Attack an entity
stop_attack	Stop attacking
get_nearby_entities	List nearby entities
send_chat	Send chat message
whisper	Private message a player
get_players	List online players
use_item	Use held item
eat	Eat food
sleep	Sleep in a bed
wake	Wake up
collect_block	Collect specific blocks
activate_block	Interact with a block

💡 Example Usage

Connecting to a Server

Connect to my local Minecraft server at localhost:25565 with username "AIBot"

Mining Diamonds

Find diamond ore near me and navigate to collect it

Building

Build a 3x3 cobblestone platform at my current position

Combat

Find and attack any zombies within 20 blocks

Crafting

Craft a wooden pickaxe using the wood in my inventory

🏗️ Development

# Run in development mode with auto-reload
npm run dev

# Build for production
npm run build

# Start the built server
npm start

🔐 Authentication

Offline Mode (Default)

For servers with online-mode=false:

Connect with auth: "offline"

Microsoft Account

For online servers (requires Microsoft account):

Connect with auth: "microsoft"

Note: Microsoft authentication will open a browser window for login.

⚠️ Known Limitations

1. No GUI: The bot operates headlessly - no game window is displayed
2. Server Compatibility: Works best with vanilla Minecraft servers
3. Version Support: Supports Minecraft 1.8 through 1.21+
4. Single Bot: Currently supports one bot connection at a time

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

📄 License

MIT License - feel free to use this in your own projects!

🙏 Credits

• Mineflayer - The amazing Minecraft bot framework
• PrismarineJS - For all the Minecraft tooling
• Anthropic - For the MCP specification
• Built with ❤️ by Harjot Singh Rana for the AI gaming revolution