Content
# Minecraft Redstone MCP — AI-Powered Redstone Circuit Design, Simulation, and Construction System
Built on top of [FundamentalLabs/minecraft-mcp](https://github.com/FundamentalLabs/minecraft-mcp), this extension adds structured design, simulation verification, and automated construction capabilities for redstone circuits to AI Agents.
## Architecture
```
User Natural Language → Agent (Claude) → MCP Server → Mineflayer Bot → Minecraft
↑ ↑
SKILL.md (Knowledge) Nucleation (Simulation Engine)
```
**Three-Layer Collaboration**:
1. **Knowledge Layer** (SKILL.md): Agent reads circuit classification, encoding format, and construction constraints.
2. **Simulation Layer** (nucleation_bridge.py): Logical verification before construction, 9/9 circuits passed.
3. **Execution Layer** (buildRedstoneCircuit.ts): Automated placement of `/setblock` commands in-game.
## In-Game Verification Results (2026-07-25)
| Circuit | Test Results |
|------|---------|
| NOT Gate | 2/2 ✅ |
| AND Gate | 4/4 ✅ |
| NAND Gate (AND→NOT chain) | 4/4 ✅ |
| 3-bit Carry Adder | 4/4 ✅ |
## Quick Start
### 1. Install Dependencies
```bash
cd mcp-server
npm install
npm run build
pip install nucleation
```
### 2. Configure Claude Desktop
`~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"minecraft": {
"command": "node",
"args": ["/path/to/mcp-server/dist/mcp-server.js"]
}
}
}
```
### 3. Usage
1. Open Minecraft Java 1.20.1+, enter the world, and enable LAN access.
2. Restart Claude Desktop.
3. Example conversations:
- "Join the game, port 25565"
- "Build an AND gate under my feet"
- "Simulate and verify the XOR gate"
## MCP Tools
| Tool | Function |
|------|------|
| `joinGame` | Bot joins the game |
| `leaveGame` | Bot leaves the game |
| `buildRedstoneCircuit` | Construct standard redstone circuits (16 templates) |
| `simulateRedstoneCircuit` | Simulate and verify circuit correctness |
| `scanRedstoneCircuit` | Scan existing circuits, identify components and patterns |
| `diffRedstoneCircuit` | Calculate differences between two circuit templates |
## File Structure
```
mcp-server/
├── src/
│ ├── skills/verified/
│ │ ├── buildRedstoneCircuit.ts # Construction tool
│ │ ├── simulateRedstoneCircuit.ts # Simulation tool
│ │ ├── scanRedstoneCircuit.ts # Scanning tool
│ │ └── diffRedstoneCircuit.ts # Difference tool
│ ├── lib/
│ │ ├── terrainDetector.ts # Terrain detection
│ │ ├── redstonePowerRules.ts # Redstone power rules
│ │ └── redstoneGraph.ts # Signal graph engine
│ └── skillRegistry.ts # Tool registry
├── scripts/
│ ├── nucleation_bridge.py # Nucleation simulation bridge
│ ├── build-2bit-adder.cjs # 2-bit adder construction script
│ └── test-2bit-adder.cjs # 2-bit adder test script
├── dist/ # Compilation output
└── package.json
```
Agent Skill file located at `~/.claude/skills/minecraft-redstone-coding/SKILL.md` (~1050 lines).
## Construction Constraints (Verified In-Game)
| Rule | Description |
|------|------|
| Glass base | Superflat world grass conducts electricity globally, must be isolated with glass |
| No wire overlap on mounting stones | Connection between gates `< mountPos`, otherwise wall torches drop |
| Command delay ≥200ms | Faster commands may be discarded by the server |
| Redstone blocks must be on the same Y layer | Redstone blocks can only energize adjacent gray wires on the same Y layer |
| Circuit distance from Bot ≤50 blocks | `blockAt()` returns null if the chunk is not loaded |
## Dependencies and Acknowledgements
This project is built on top of the following open-source projects:
| Project | License | Usage |
|------|------|------|
| [FundamentalLabs/minecraft-mcp](https://github.com/FundamentalLabs/minecraft-mcp) | MIT | MCP Server foundation, 30 verified skills |
| [Mineflayer](https://github.com/PrismarineJS/mineflayer) | MIT | Minecraft Bot API (Java edition) |
| [mineflayer-pathfinder](https://github.com/PrismarineJS/mineflayer-pathfinder) | MIT | A\* pathfinding |
| [mineflayer-pvp](https://github.com/PrismarineJS/mineflayer-pvp) | MIT | PVP combat |
| [mineflayer-tool](https://github.com/PrismarineJS/mineflayer-tool) | MIT | Automated tool selection |
| [mineflayer-collectblock](https://github.com/PrismarineJS/mineflayer-collectblock) | MIT | Block collection |
| [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) | MIT | MCP protocol implementation |
| [Nucleation](https://github.com/Schem-at/Nucleation) | AGPL-3.0 | Redstone simulation engine (Schematic + CircuitBuilder + MCHPRS) |
| [Vec3](https://github.com/PrismarineJS/node-vec3) | MIT | 3D vector operations |
## License
This project is based on FundamentalLabs/minecraft-mcp (MIT) and extended.
- Source code: MIT License
- Nucleation bridge component: AGPL-3.0 (inherited from Nucleation)
- SKILL.md knowledge document: CC-BY-4.0
See LICENSE files in each subdirectory for details.
## Known Limitations
- Manual block-level layout for multi-torch circuits (XOR/HalfAdder/FullAdder) not fully verified — requires Nucleation MCHPRS block-level simulation support (Phase 3)
- Construction requires Minecraft cheats enabled (`/setblock` requires OP privileges)
- Bot joins via LAN, requires the same network
- Only supports Minecraft Java edition 1.20.1+
🤖 Generated with [Claude Code](https://claude.com/claude-code)
