Mindustry MCP

MCP (Model Context Protocol) server + companion mod for Mindustry, allowing AI models to interact with in-game logic processors, read game state, and generate schematics.

What it does

AI models (via Claude, or any MCP-compatible client) can:

• Write mlog code directly into in-game processors
• Read game state — resources, wave, map info, block properties
• Read logic blocks — processors, messages, memory cells, switches, displays
• Generate schematics — create .msch files with processors, factories, and mlog code
• Validate & reference mlog — syntax checking and instruction reference

Architecture

┌─────────────┐     stdio      ┌─────────────────┐     TCP:9876     ┌──────────────┐
│  AI Client   │◄──────────────►│   MCP Server    │◄────────────────►│  Mindustry   │
│ (Claude etc) │                │  (Kotlin JAR)   │                  │  (with mod)  │
└─────────────┘                └─────────────────┘                  └──────────────┘
                                 Offline tools:                       Companion mod:
                                 - mlog reference                     - TCP bridge
                                 - mlog validate                      - Processor R/W
                                 - schematic create                   - Game state
                                 - schematic read                     - Message read

Three Gradle modules:

• mcp-server — Kotlin MCP server with 15 tools (offline + online)
• mindustry-mod — Java companion mod for Mindustry v158+
• shared — Bridge protocol definitions

MCP Tools

Offline (always available)

| Tool | Description | |------|-------------| | mlog_reference | Instruction reference (by name, category, or topic) | | mlog_validate | Syntax validation for mlog code | | mlog_generate | Code templates for common tasks | | schematic_create | Create .msch schematics with blocks and processors | | schematic_read | Parse and display schematic contents | | schematic_add_processor | Add a processor to an existing schematic |

Online (requires game connection)

| Tool | Description | |------|-------------| | game_connect | Connect to Mindustry with companion mod | | game_disconnect | Disconnect from game | | game_status | Map, wave, resources, unit count | | game_sensor | Read any block property (@health, @copper, etc.) | | logic_blocks_list | List ALL logic blocks (processors, messages, memory, switches, displays) | | processor_list | List processors with code info | | processor_read | Read mlog code and links from a processor | | processor_write | Write mlog code to a processor (preserves links) | | message_read | Read text from a message block |

Setup

Requirements

• Java 17+ (for building; JDK 21 is downloaded automatically for Gradle)
• Mindustry v158+

Build

./gradlew :mcp-server:shadowJar :mindustry-mod:jar

Outputs:

• mcp-server/build/libs/mindustry-mcp-server-0.1.0.jar — MCP server
• mindustry-mod/build/libs/mindustry-mcp-mod-0.1.0.jar — Mindustry mod

Install the mod

Copy mindustry-mcp-mod-0.1.0.jar to your Mindustry mods folder:

• Windows: %APPDATA%\Mindustry\mods\
• Linux: ~/.local/share/Mindustry/mods/
• macOS: ~/Library/Application Support/Mindustry/mods/

Configure MCP client

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json or Claude Code .claude.json):

{
  "mcpServers": {
    "mindustry": {
      "command": "java",
      "args": ["-jar", "/path/to/mindustry-mcp-server-0.1.0.jar"]
    }
  }
}

Usage

1. Launch Mindustry (mod loads automatically, bridge starts on port 9876)
2. Start your MCP client — offline tools work immediately
3. Use game_connect to connect to the running game
4. AI can now read/write processors, monitor resources, generate schematics

Example: AI writes a resource monitor

You: "Write code to the processor at (115, 79) that shows core resources on the linked message block"

AI calls: processor_write(x=115, y=79, code="
  getlink core 0
  getlink msg 1
  sensor copper core @copper
  sensor lead core @lead
  print \"Resources:\"
  print \"\\nCopper: \"
  print copper
  print \"\\nLead: \"
  print lead
  printflush msg
")

License

MIT