Minecraft MCP Bot
A Model Context Protocol (MCP) server that provides programmatic control of a Minecraft bot using the Mineflayer library. This project enables AI assistants to interact with Minecraft through a clean, extensible interface.
Project Goals
- AI-Controlled Minecraft Bot: Create an intelligent bot that can be controlled through natural language commands via MCP
- Full Mineflayer API Access: Provide comprehensive access to Minecraft bot capabilities through a generic command interface
- Intelligent Navigation: Implement pathfinder-based movement for precise, obstacle-aware navigation
- Extensible Architecture: Build a modular system that can be easily extended with new capabilities
- Training Environment: Establish a safe, flat-world testing ground for bot behavior development
- Clean Integration: Seamless integration with VS Code and AI assistants through MCP protocol
Features
Current Capabilities
- Generic Command Interface: Execute any Mineflayer bot command with flexible parameter handling
- Intelligent Pathfinding: Navigate to specific coordinates with obstacle avoidance
- Chat Communication: Send messages and interact with players
- Entity Detection: Scan for and interact with nearby players, mobs, and objects
- Flexible Movement: Both manual control states and intelligent pathfinding options
- Safe Testing Environment: Operates in a flat world to prevent terrain-related issues
Tools Available
execute-bot-command
: Generic interface for all Mineflayer API functionspathfind-to-position
: Intelligent navigation to specific coordinates
Technical Stack
- Mineflayer: Core Minecraft bot library
- MCP SDK: Model Context Protocol server implementation
- Pathfinder: Intelligent navigation and movement
- Zod: Schema validation for tool parameters
- Node.js: Runtime environment
Getting Started
Prerequisites
- Node.js (v20+)
- Minecraft server (configured for flat world)
- VS Code with MCP extension
Installation
Configuration
- Update server connection details in
index.js
- Configure MCP in VS Code settings (
.vscode/mcp.json
) - Ensure Minecraft server is running with flat world generation
Running
Development
Branch Structure
main
: Stable, production-ready codeadd-pathfinder
: Pathfinding integration development- Feature branches for new capabilities
Contributing
- Create feature branches for new development
- Test thoroughly in flat world environment
- Ensure clean integration with existing MCP tools
- Commit incremental changes with clear messages
Future Enhancements
- Building and Construction: Block placement and structure creation
- Inventory Management: Item handling and crafting capabilities
- Advanced AI Behaviors: Complex task execution and planning
- Multi-Bot Coordination: Manage multiple bots simultaneously
- Real-World Integration: Connect to live Minecraft servers safely
Security Considerations
⚠️ IMPORTANT SECURITY WARNING ⚠️
This project currently provides unrestricted access to the Mineflayer API through the generic command interface. This means:
- Any Mineflayer command can be executed without validation or restrictions
- The LLM has full bot control including potentially destructive actions
- No command filtering or sandboxing is currently implemented
- Suitable for trusted environments only (local testing, controlled servers)
Current Risk Level: HIGH
- ✅ Safe for: Local development, private servers, controlled testing
- ❌ NOT safe for: Public servers, untrusted environments, production use
- 🔥 It could set your world on fire. 🔥
Recommended Security Improvements (Future Development)
- Command Whitelist: Restrict available commands to approved set
- Parameter Validation: Strict validation of command parameters
- Action Limits: Rate limiting and scope restrictions
- Audit Logging: Track all executed commands
- Permission System: Granular control over bot capabilities
- Safe Mode: Default to restricted command set
Architecture Philosophy
This project emphasizes:
- Simplicity: Clean, minimal codebase with focused functionality
- Flexibility: Generic interfaces that adapt to diverse use cases
- Controlled Testing: Safe environment for development and experimentation
- Extensibility: Modular design for easy capability expansion
- Security Awareness: Recognizing and documenting security implications
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables AI assistants to control a Minecraft bot through natural language commands using the Mineflayer library. Provides intelligent pathfinding, chat communication, entity detection, and generic access to Minecraft bot capabilities.