TRAE-MC: The Ultimate Minecraft MCP AI Agent

"Transform TRAE into a god-like Minecraft entity — 500+ commands, 10 transformation modes, datapack manipulation, and intelligent automation."

📖 Table of Contents

1. Overview
2. Features
3. Installation
4. Usage
5. Commands Overview
6. Transformation Modes
7. Datapack System
8. Architecture
9. Configuration
10. Troubleshooting
11. Contributing
12. License
13. FAQ

Overview

TRAE-MC is a ground-breaking enhancement to the standard Minecraft MCP (Model Context Protocol) server. While basic MCP implementations allow AI to read game state and execute simple commands, TRAE-MC transforms the AI into a truly intelligent in-game entity capable of executing over 500 distinct commands, switching between 10 transformation modes, manipulating datapacks in real-time, and making context-aware decisions.

This project was written by TRAE itself — a demonstration of what AI can build when given the right tools and prompts.

Why TRAE-MC?

| Problem | TRAE-MC Solution | |---------|------------------| | Basic MCP has ~20 commands | 500+ structured commands | | No role-based behavior | 10 transformation modes | | No datapack manipulation | Full real-time datapack editing | | No batch operations | Natural language batch building | | No safety system | Auto-backup & confirmation dialogs |

Features

Core Statistics

• 500+ distinct commands
• 10 transformation modes
• 20+ command categories
• 100% open source
• Minecraft 1.20.4 – 1.21.4 support

Feature Matrix

| Category | Commands | Description | |----------|----------|-------------| | Mode Switching | 10 | Change AI behavior roles | | World Editing | 60+ | Setblock, fill, clone, sphere, cylinder, pyramid | | Entity Control | 50+ | Spawn, modify, kill, ride, leash | | Building Generation | 45+ | Houses, towers, villages, roads, bridges | | Combat System | 35+ | Attack, defend, mob farm, boss fight | | Redstone Engineering | 30+ | Logic gates, clocks, piston extenders | | Datapack Management | 40+ | Create, modify, deploy, validate | | Inventory Management | 35+ | Sort, craft, smelt, enchant, repair | | Exploration | 30+ | Locate, map, waypoint, teleport | | Chat & Social | 25+ | Auto-reply, broadcast, moderation | | Utility & Debug | 80+ | Performance, logging, export, backup | | Chaos (Random) | 60+ | Random effects and unpredictable fun |

Installation

Prerequisites

• Minecraft Java Edition (1.20.4 – 1.21.4)
• Fabric or Quilt mod loader
• MCP server running locally
• TRAE CLI or desktop app (v1.5+)
• Node.js 18+

Step 1: Install Minecraft MCP Server

git clone https://github.com/minecraft/mcp-server.git
cd mcp-server
npm install
npm run build
npm start
Step 2: Configure TRAE
Edit ~/.trae/config.json:

json
{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "MC_HOST": "localhost",
        "MC_PORT": "25565"
      }
    }
  },
  "traeMc": {
    "enableSuperCommands": true,
    "defaultMode": "architect",
    "autoBackup": true
  }
}
Step 3: Install Companion Mod
Download from Releases and place in mods/ folder.

Step 4: Connect
Launch Minecraft with the mod

Open world to LAN (Allow Cheats: ON)

In TRAE: /traec connect

Success message: [TRAE-MC] Connected!

Usage
Basic Commands
text
/trae mode architect          # Switch to architect mode
/trae sphere ~ ~ ~ 5 stone    # Create a stone sphere
/tae fill ~10 ~ ~ ~20 ~10 ~10 oak_planks  # Fill a region
/trae summon zombie custom    # Summon a custom zombie
Batch Building (Natural Language)
text
/trae build "a medieval castle with 4 towers and a moat"
/trae build "wheat farm 20x20 with water source"
/trae build "redstone automatic door 3x3"
Datapack Operations
text
/trae datapack create "my_pack"
/trae datapack add_loot "chests/treasure" "diamond_sword"
/trae datapack add_recipe "my_sword" "diamond,stick"
/trae datapack deploy
Commands Overview
Mode Commands (10)
Command	Effect
/trae mode architect	Creative building, WorldEdit integration
/trae mode admin	Full OP powers, server management
/trae mode survivalist	Auto-eat, combat optimization
/trae mode summoner	Spawn any entity with NBT
/trae mode redstone	Redstone automation templates
/trae mode datawizard	Datapack creation and editing
/trae mode explorer	Auto-mapping, structure locating
/trae mode farmer	Crop automation, villager trading
/trae mode miner	Branch mining, ore tracing
/trae mode chaos	Random unpredictable effects
World Editing (Sample)
text
/trae setblock <x> <y> <z> <block>
/trae fill <x1> <y1> <z1> <x2> <y2> <z2> <block>
/trae clone <x1> <y1> <z1> <x2> <y2> <z2> <x> <y> <z>
/trae sphere <x> <y> <z> <radius> <block> [hollow]
/trae cylinder <x> <y> <z> <radius> <height> <block>
/trae pyramid <x> <y> <z> <size> <block>
/trae wall <x1> <z1> <x2> <z2> <height> <block>
Entity Control (Sample)
text
/trae spawn <entity> [count] [custom_name]
/trae kill @e[type=zombie,r=10]
/trae ride <player> <entity>
/trae leash <entity> <x> <y> <z>
/trae heal <entity>
/trae effect <entity> <effect> <duration> <amplifier>
Building Generation (Sample)
text
/trae build house <style> [size]
/trae build tower <height> <material>
/trae build village <radius> <house_count>
/trae build bridge <x1> <z1> <x2> <z2>
/trae build castle < size> <material>
/trae build farm <crop> <width> <length>
Redstone (Sample)
text
/trae redstone clock <period> <location>
/trae redstone piston_door <width> <height>
/trae redstone elevator <floors>
/trae redstone calculator <operation> <inputs>
/trae redstone timer <seconds>
Datapack (Sample)
text  文本
/trae datapack create <name>
/trae datapack add_loot <path> <item>
/trae datapack add_recipe <name> <ingredients>
/trae datapack add_advancement <name> <criteria>
/trae datapack add_tag <type> <name> <values>
/trae datapack add_function <name> <commands>
/trae datapack add_predicate <name> <conditions>
/trae datapack validate
/trae datapack deploy
/trae datapack reload
Combat (Sample)
text
/trae combat attack <target>
/trae combat defend <duration>
/trae combat kite <target> <distance>
/trae combat flee <direction> <distance>
/trae combat mob_farm <type> <size>
/trae combat boss <type> [difficulty]
Inventory (Sample)
text
/trae inventory sort [chest|player]
/trae inventory craft <recipe> <quantity>
/trae inventory smelt <item> <quantity>
/trae inventory enchant <item> <enchantment> <level>
/trae inventory repair <item>
/trae inventory deposit <item> <quantity>
Exploration (Sample)
text
/trae explore locate <structure>
/trae explore map <radius>
/trae explore waypoint add <name> <x> <y> <z>
/trae explore cave <mode> [depth]
/trae explore biome <biome>
/trae explore ore <ore_type> <radius>
Teleport & Movement (Sample)
text
/trae tp <x> <y> <z>
/trae tp player <player>
/trae tp home
/trae tp spawn
/trae tp waypoint <name>
/trae fly [on|off]
/trae speed <walk|fly> <value>
Utility (Sample)
text
/trae backup [name]
/trae rollback <time>
/trae export world <format>
/trae export region <x1> <z1> <x2> <z2>
/trae stats
/trae debug start|stop
/trae log <level> <message>
/trae help [command]
Chaos Mode (Sample - 60 random effects)
text
/trae chaos random_block     # Random block type
/trae chaos random_teleport  # Random TP within 1000 blocks
/trae chaos swap_inventory   # Swaps with nearest player
/trae chaos rain_anvils      # Anvils fall for 10 seconds
/trae chaos super_jump       # 10x jump height for 30s
/trae chaos fireworks        # Continuous fireworks display
Transformation Modes
Architect Mode
Instant block placement and destruction

Unlimited block reach

WorldEdit-style region operations

Schematic paste (schematic files)

Terrain sculpting tools

Admin Mode
Full operator privileges

Player management (kick/ban/mute)

Server properties modification

World management (create/delete/load/unload)

Plugin/mod control

Survivalist Mode
Auto-eating when hunger < 18

Combat prediction (best weapon/tool suggestions)

Tool durability warnings

Night vision on demand

Auto-collect resources

Summoner Mode
Spawn any entity with full NBT

Custom boss creation (health, abilities, drops)

Entity riding control

Mass mob leash/unleash

Entity pathfinding control

Redstone Engineer Mode
Logic gate templates (AND, OR, NOT, XOR)

Clock generators (all speeds)

Piston door wizards

Elevator systems  电梯系统

Redstone calculator templates

Timer/delay circuits

Data Wizard Mode
Create complete datapack structure

Modify loot tables in real time

Create/edit advancements

Write recursive functions

Create complex predicates

Validate and deploy datapacks

Explorer Mode
Auto-chunk mapping

Structure locating (stronghold, bastion, monument, etc.)

Waypoint navigation system

Cave system mapping

Altitude profiling

Nearest POI detection

Farmer Mode
Auto-plant/harvest in defined areas

Villager trading automation

Animal breeding scheduler

Bone meal optimizer

Crop growth prediction

Composter automation

Miner Mode
Fishbone/branch mining pattern generator

Ore vein tracing

Lava warning system

Explosion-resistant mining

Fortune optimizer (suggests best tool)

Tunnel boring at any angle

Chaos Mode
Every 30 seconds: random command execution

Weighted random probabilities

Can be disabled mid-session

Includes harmless fun to devastating effects

Cooldown override available

Datapack System
TRAE-MC includes a full datapack management system that operates at runtime.

Creating a Datapack
text
/trae datapack create "my_awesome_pack"
This creates:

text
my_awesome_pack/
├── pack.mcmeta
├── data/
│   └── my_awesome_pack/
│       ├── advancements/
│       ├── functions/
│       ├── loot_tables/
│       ├── predicates/
│       ├── recipes/
│       └── tags/
Adding Content Examples
Loot Table:

text
/trae datapack add_loot "my_pack:chests/treasure" "diamond_sword" "minecraft:sharpness" 5
Recipe:

text
/trae datapack add_recipe "my_pack:ultimate_sword" "diamond_block,netherite_ingot,nether_star"
Advancement:

text
/trae datapack add_advancement "my_pack:first_trae_command" "trae:trae_command_executed"
Function with 50 commands:

text
/trae datapack add_function "my_pack:init" --commands @generate 50
Architecture  架构
text  文本
┌─────────────────────────────────────────────────────────┐
│                      TRAE (AI Engine)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │  System     │  │  Command    │  │  Context    │     │
│  │  Prompt     │──│  Parser     │──│  Memory     │     │
│  │  (500+ cmds)│  │             │  │             │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────│───────────────────────────────┘
                          │ MCP Protocol
                          ▼
┌─────────────────────────────────────────────────────────┐
│              MCP Server (Python/Node.js)                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │  Command    │  │  Event      │  │  State      │     │
│  │  Router     │──│  Handler    │──│  Manager    │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────│───────────────────────────────┘
                          │ RCON / WebSocket
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Minecraft Server + Mod                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │  Command    │  │  Datapack   │  │  World      │     │
│  │  Executor   │──│  Injector   │──│  Access     │     │
│  └─────────────┘  └─────────────┘  └─────────────┘     │
└─────────────────────────────────────────────────────────┘
Data Flow
User types command → TRAE processes with system prompt

TRAE sends normalized commands via MCP

MCP server validates and routes

Minecraft mod executes and returns result

Result flows back to TRAE for next action

Configuration
Full Configuration File
json
{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["./mcp-server/dist/index.js"],
      "env": {
        "MC_HOST": "localhost",
        "MC_PORT": "25565",
        "MC_PASSWORD": "",
        "MC_AUTH": "offline"
      }
    }
  },
  "traeMc": {
    "enableSuperCommands": true,
    "defaultMode": "architect",
    "autoBackup": true,
    "backupInterval": 300,
    "maxCommandHistory": 1000,
    "confirmDestructive": true,
    "chaosModeCooldown": 30,
    "logLevel": "info",
    "commandAliases": {
      "b": "build",
      "tp": "teleport",
      "sum": "summon"
    },
    "disabledCommands": [],
    "customCommandsPath": "./custom_commands.json"
  }
}
Troubleshooting
Connection Failed
bash
# Check if Minecraft is running with mod
# Run this command manually in Minecraft:
/trae test

# Check MCP server logs
tail -f ~/.trae/logs/mcp.log

# Verify port  # 验证端口
netstat -an | grep 25565
Commands Not Working  命令无法使用
Ensure cheats are ON (/op yourself first)

Check mode: /trae mode shows current mode

Try explicit mode switch: /trae mode admin

Check MCP server is running

Datapack Issues
bash
/trae datapack validate my_pack
/trae datapack reload
# Check game logs for syntax errors
Contributing
We welcome contributions!

Ways to Contribute
Add new commands (target: 1000+)

Create schematic templates

Write documentation

Report bugs

Suggest features

Adding a New Command
Fork the repository

Add command to commands/your_category.js

Register in command-registry.json

Update system prompt

Submit pull request

Command Format
javascript
{
  "name": "spiral_tower",
  "category": "building",
  "description": "Generate a spiral tower",
  "syntax": "/trae spiral_tower <height> <radius> <block>",
  "examples": ["/trae spiral_tower 50 5 stone_bricks"],
  "permission": "architect",
  "handler": (args, context) => { /* implementation */ }
}
License
MIT License - see LICENSE file for details.

FAQ
Q: Does this work on multiplayer servers?
A: Yes, but you need OP permissions.

Q: Can I use this without TRAE?
A: No, TRAE-MC is specifically designed for TRAE's AI architecture.

Q: Will this affect my vanilla gameplay?  Q：这会影响我的原版游戏体验吗？
A: Only when you execute commands. Your vanilla world remains intact.  A：只有在执行命令时才会影响。你的原版世界保持不变。

Q: How many commands total?  Q：总共有多少个命令？"
A: 500+ distinct commands. Including variations and aliases: 800+.

Q: Can I add my own commands?
A: Yes, use customCommandsPath in config.

Q: Is there a GUI?
A: TRAE provides a desktop app interface. Minecraft side is command-based.

Q: Does it support Forge?
A: Currently Fabric/Quilt only. Forge support planned for v3.0.

Q: Can TRAE build an entire city by itself?
A: Yes. Use /trae build "city with 100 buildings" — it will generate schematics and place them.

Credits
Written by TRAE AI

Inspired by Minecraft MCP protocol

Special thanks to The Minecraft modding community

Star History
https://api.star-history.com/svg?repos=yourusername/trae-mc&type=Date

Built with TRAE. Deployed with love. Run with /trae mode chaos if you dare.