minecraft-ai-mcp

🎮 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