Minecraft Dev MCP

A Model Context Protocol server that gives AI assistants native access to Minecraft mod development tools — decompile, remap, search, and analyze Minecraft source code directly from your AI workflow.

Quick Start

Prerequisites

| Requirement | Details | | --- | --- | | Node.js 18+ | nodejs.org | | Java 17+ | Required for decompilation and remapping • Verify with java -version • Adoptium or Oracle JDK |

Installation

| Method | Command | | --- | --- | | NPM (Recommended) | npm install -g @mcdxai/minecraft-dev-mcp | | NPX (No Install) | Use npx -y @mcdxai/minecraft-dev-mcp directly in config | | From Source | See the Development section |

Claude Desktop

Add to your Claude Desktop configuration file:

| Platform | Config Path | | --- | --- | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

NPM installation:

{
  "mcpServers": {
    "minecraft-dev": {
      "command": "minecraft-dev-mcp"
    }
  }
}

NPX (no installation required):

{
  "mcpServers": {
    "minecraft-dev": {
      "command": "npx",
      "args": ["-y", "@mcdxai/minecraft-dev-mcp"]
    }
  }
}

Claude Code

Add to .claude/settings.local.json in your project, or to your global Claude Code settings:

{
  "mcpServers": {
    "minecraft-dev": {
      "command": "minecraft-dev-mcp"
    }
  }
}

HTTP Transport

For clients or editors that connect over HTTP instead of stdio, start the server in HTTP mode. It uses the MCP Streamable HTTP transport with per-session isolation.

| Flag | Description | | --- | --- | | --http | Start with the Streamable HTTP transport instead of stdio | | --port <number> | Port to listen on (default: 3000) — also implies --http | | --host <address> | Host to bind to (default: 127.0.0.1) |

minecraft-dev-mcp --http --port 3000

The MCP endpoint is http://<host>:<port>/mcp (POST to call, GET for the SSE stream, DELETE to end a session). Each client gets its own session, so multiple clients can connect concurrently.

Security: the default host 127.0.0.1 enables the SDK's DNS-rebinding protection automatically. Binding to a non-loopback host (e.g. --host 0.0.0.0) disables that protection — only do so on a trusted network, ideally behind a reverse proxy or auth.

CLI

A standalone CLI (minecraft-dev-cli) invokes the same tools directly — no MCP client required — for scripts, skills, and automation. Arguments are flags-only (--key value or --key=value) to avoid the JSON-quoting issues positional JSON arguments cause in PowerShell and other shells.

# List every tool with its parameters
minecraft-dev-cli list-tools

# Invoke a tool with flags
minecraft-dev-cli get_minecraft_source --version 1.21.10 --className net.minecraft.world.entity.Entity --mapping yarn

# Boolean / numeric / JSON values are coerced automatically
minecraft-dev-cli analyze_mod_jar --jarPath C:\mods\example.jar --includeAllClasses true

Output is always JSON: { "success": true, "tool": "...", "result": ... } on success, or { "success": false, "tool": "...", "error": "..." } with exit code 1 on failure. Run minecraft-dev-cli help for full usage.

Features

| Feature | Description | | --- | --- | | On-demand decompilation | Download, remap, and decompile any Minecraft version (1.14+) on first use — cached for instant access afterward | | Multiple mapping namespaces | Yarn, Mojmap (official), Intermediary, and obfuscated — translate any symbol between them with find_mapping | | Decompiled source access | Retrieve Java source for any Minecraft class with optional line-range filtering | | Mod JAR analysis | Analyze Fabric, Quilt, Forge, and NeoForge mods — metadata, mixins, dependencies, entry points — and decompile them | | Mixin, Access Widener & Access Transformer validation | Validate Mixin annotations, Fabric .accesswidener files, and Forge/NeoForge access transformer .cfg files against decompiled source with error reporting and fix suggestions | | Version diff | Class-level and AST-level diff between any two Minecraft versions — method signatures, field changes, breaking changes | | Full-text search | SQLite FTS5 indexes for fast BM25-ranked search across Minecraft and mod source |

21 tools across 4 categories — see docs/tools.md for the full reference.

Common Workflows

| Workflow | Steps | | --- | --- | | First-time source access | Call get_minecraft_source — server downloads, remaps, and decompiles (~5 min first run). Subsequent requests for the same version return in ~50 ms from cache. | | Analyze a third-party mod | analyze_mod_jar → remap_mod_jar → decompile_mod_jar → search_mod_code or index_mod + search_mod_indexed | | Validate a Fabric mixin | analyze_mixin with your Java source or file path — validates targets, injection points, and method selectors against the decompiled MC version. | | Find breaking changes between versions | compare_versions for a high-level overview, then compare_versions_detailed scoped to specific packages for full AST-level diffs. | | Fast broad search | index_minecraft_version once, then search_indexed with FTS5 queries: entity AND damage, "onBlockBreak", tick*, BlockEntity NOT render. | | Translate obfuscated names | find_mapping with sourceMapping: "official" to look up the Yarn or Mojmap equivalent for any class, method, or field. |

Version Support

| Version Range | Yarn | Mojmap | Notes | | --- | --- | --- | --- | | 1.14 – 1.21.11 | Full support | Full support | Obfuscated — two-step remapping required (official → intermediary → named) | | 26.1+ | Not available | Full support | Deobfuscated by Mojang — no remapping needed, classes already human-readable |

Yarn mappings are discontinued after 1.21.11, which is the last obfuscated Minecraft version. All 26.1+ releases ship with readable class and method names and only require Mojmap.

Tested versions: 1.19.4 · 1.20.1 · 1.21.10 · 1.21.11 · 26.1-snapshot-8 · 26.1-snapshot-9

Configuration

| Environment Variable | Description | | --- | --- | | CACHE_DIR | Override the default cache directory location | | LOG_LEVEL | Logging verbosity: DEBUG, INFO, WARN, ERROR |

{
  "mcpServers": {
    "minecraft-dev": {
      "command": "minecraft-dev-mcp",
      "env": {
        "CACHE_DIR": "/custom/cache/path",
        "LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Cache Location

Downloaded JARs, mappings, decompiled source, and search databases live in a platform-specific cache directory shared across all workspaces (~400–500 MB per Minecraft version).

| Platform | Cache Path | | --- | --- | | Windows | %APPDATA%\minecraft-dev-mcp | | macOS | ~/Library/Application Support/minecraft-dev-mcp | | Linux / WSL | ~/.config/minecraft-dev-mcp |

Delete the directory to clear the cache — the server re-downloads anything missing on next use. To relocate the cache anywhere on disk, set the CACHE_DIR environment variable (see Configuration).

Cache Contents

| Path | Contents | | --- | --- | | jars/ | Client and server JARs | | mappings/ | Yarn, Mojmap, and Intermediary mapping files | | remapped/ | Remapped JARs | | decompiled/<version>/<mapping>/ | Decompiled Minecraft source | | decompiled-mods/<modId>/<modVersion>/<mapping>/ | Decompiled third-party mod source | | registry/<version>/ | Extracted registry data (blocks, items, entities) | | resources/ | Java tool JARs (VineFlower, tiny-remapper) | | cache.db | SQLite metadata database | | search_index.db | SQLite FTS5 full-text search index | | minecraft-dev-mcp.log | Server log file |

Development

| Task | Command | | --- | --- | | Install dependencies | npm install | | Build | npm run build | | Dev mode (hot reload) | npm run dev | | Tests | npm test |

Build from source:

git clone https://github.com/MCDxAI/minecraft-dev-mcp.git
cd minecraft-dev-mcp
npm install
npm run build

Troubleshooting

| Issue | Solution | | --- | --- | | Java not found — Java 17+ is required but not found | Install Java 17+ from Adoptium • Verify with java -version • Ensure java is on your PATH | | Decompilation fails | Check available disk space (~500 MB per version) • Review %APPDATA%\minecraft-dev-mcp\minecraft-dev-mcp.log • Force re-decompile by passing "force": true | | Yarn not available — Yarn mappings not available for version X | Yarn is only supported for 1.14–1.21.11 • Use mojmap for 26.1+ versions | | Class not found | Use the fully qualified class name (e.g., net.minecraft.world.entity.Entity) • Verify the version is decompiled | | Registry returns no data | Registry names use singular form: block, item, entity — not blocks, items, entities | | WSL path error | Both /mnt/c/path/to/file and C:\path\to\file are accepted for all JAR path parameters |

Credits

| Project | Details | | --- | --- | | VineFlower | Modern Java decompiler by the Vineflower Team | | tiny-remapper | JAR remapping tool by FabricMC | | Yarn Mappings | Community-maintained mappings by FabricMC | | MCP SDK | Protocol implementation by Anthropic |