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 @dhjcomical/minecraft-dev-mcp | | NPX (No Install) | Use npx -y @dhjcomical/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", "@dhjcomical/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"
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project, or to the global ~/.cursor/mcp.json:

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

VS Code (Copilot / MCP extension)

Add to .vscode/mcp.json in your workspace:

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

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.minecraft-dev]
command = "npx"
args = ["-y", "@dhjcomical/minecraft-dev-mcp"]

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

Gemini CLI

Add to ~/.gemini/settings.json:

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

Note: the examples above use npx so no install step is needed. If you installed globally (npm install -g @dhjcomical/minecraft-dev-mcp), replace command/args with "command": "minecraft-dev-mcp" (no args). On Windows, make sure the global npm bin directory is on your PATH.

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.

Agent Skill (no MCP client required)

Some agents (Cursor, Codex, Copilot, generic CLI agents) don't connect over MCP. For those, install the bundled agent skill so the agent knows when and how to call minecraft-dev-cli:

# Global install exposes both the CLI and the skill files
npm install -g @dhjcomical/minecraft-dev-mcp

# Find where the skill was installed
npm root -g
# → <global-root>/@dhjcomical/minecraft-dev-mcp/skills/minecraft-dev

Copy the minecraft-dev skill folder to your agent's skill directory:

| Agent | Skill directory | | --- | --- | | Claude Code | ~/.claude/skills/minecraft-dev (personal) or <project>/.claude/skills/minecraft-dev (shared) | | Cursor | <project>/.cursor/skills/minecraft-dev | | Codex CLI | ~/.codex/skills/minecraft-dev | | OpenCode | ~/.config/opencode/skills/minecraft-dev |

The skill's frontmatter tells the agent when to invoke it (any question about net.minecraft.*, mappings, registries, mixins, mod JARs, ...), and references/tools.md gives it exact flags per tool. Ensure minecraft-dev-cli is on the agent's PATH.

Features

| Feature | Description | | --- | --- | | On-demand decompilation | Download, remap, and decompile any Minecraft version (alpha 1.0.10+) on first use — cached for instant access afterward | | Multiple mapping namespaces | Yarn, Mojmap (official), Intermediary, Feather/Calamus (Ornithe, pre-1.7.10), MCP (pre-1.14.4), 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 & loader-aware remapping | Analyze Fabric, Quilt, Forge, and NeoForge mods — metadata, mixins, dependencies, entry points — then remap with the right loader path (Fabric intermediary → yarn/mojmap/feather; Forge/NeoForge 1.7.10–1.13.2 SRG members → MCP names) and decompile them | | Mixin, Access Widener & Access Transformer validation | Validate Mixin annotations, Fabric .accesswidener files, and Forge/NeoForge access transformer .cfg files with error reporting and fix suggestions. Access widener/transformer checks run against the game's real bytecode, catching inherited members, record constructors, inner-class reachability, and conflicts across multiple AT files | | 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. Works for every loader era: Fabric/Quilt, Forge 1.13+/NeoForge (mods.toml), and legacy Forge 1.6.4–1.12.2 (mcmod.info). | | Read a legacy Forge mod (1.7.10–1.12.2) | analyze_mod_jar reads mcmod.info (id, version, mcversion, dependencies, @Mod entry point, coremod interface, manifest-declared mixin configs and ATs) → remap_mod_jar (SRG → MCP, loader + version auto-detected) → decompile_mod_jar. | | 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 / Feather | Mojmap | MCP | Notes | | --- | --- | --- | --- | --- | | a1.0.10 – 1.6.4 | Full support (Feather) | Not available | Not available | Obfuscated — Ornithe calamus → feather two-step remap; pre-1.3 versions use split -client/-server artifacts (the client JAR is the target) | | 1.7.10 – 1.13.2 | Not available | Not available | Full support | Obfuscated — Forge MCP mappings reconstructed from mcp:srg joined.srg (1.7.10–1.12.2) or mcp_config joined.tsrg (1.13.x) + mcp_stable CSV; single-step remap with ignoreFieldDesc | | 1.14 – 1.21.11 | Full support (Yarn) | Full support | Not supported | Obfuscated — two-step remapping required (official → intermediary → named) | | 26.1+ | Not available | Full support | Not supported | Deobfuscated by Mojang — no remapping needed, classes already human-readable |

Not supported: 1.10.1 (no mcp:<v>:srg zip published) and pre-alpha versions (rd-*/classic — Ornithe starts at alpha 1.0.10). Requests for unsupported versions fail fast with a clear error.

Registry extraction (get_registry_data) requires the Minecraft data generator (1.13+) and is not supported for 1.12.2 and earlier — alpha/beta ids fail fast with a clear error.

Third-party mod support by era

The mod tools are loader-era aware, not version-gated. Everything upstream of decompilation reads the JAR's own metadata:

| Mod era | Metadata source | analyze_mod_jar | remap_mod_jar | AT validation | | --- | --- | --- | --- | --- | | Fabric/Quilt (1.14+) | fabric.mod.json / quilt.mod.json | id, version, deps, entry points, mixins, access widener | intermediary → yarn/mojmap/feather | n/a (access widener) | | Forge 1.13 – 1.20.x / NeoForge | META-INF/mods.toml / neoforge.mods.toml | id, version, deps with version ranges and sides, mixins, access transformers, @Mod entry point | SRG → MCP for 1.13–1.13.2 (1.14+ has no published SRG→member mappings) | mojmap (1.17+); mcp for 1.13.x | | Legacy Forge 1.6.4 – 1.12.2 | mcmod.info + MANIFEST.MF | id, version, mcversion, requiredMods/dependencies, @Mod + coremod entry points, manifest-declared mixin configs and FMLAT access transformers | SRG → MCP (loader and version auto-detected) | mapping: "mcp" — SRG member ids resolved to MCP names |

analyze_mod_jar also takes mixin targets from @Mixin bytecode (both RetentionPolicy.RUNTIME and CLASS, where Mixin actually lives) and reports anything it could not determine in a warnings array instead of inventing a value. decompile_mod_jar refuses to cache a mod whose id/version it could not detect, rather than writing it to a shared placeholder directory.

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: b1.7.3 (Feather) · 1.4.7 (Feather) · 1.7.10 (MCP) · 1.8.9 (MCP) · 1.12.2 (MCP) · 1.13.2 (MCP) · 1.14.3 (Yarn) · 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, Intermediary, Feather/Calamus, and MCP 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/DHJComical/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 • Pre-1.7.10 versions use feather • 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 | | Ornithe | Feather & Calamus mappings for pre-1.7.10 Minecraft by the Ornithe Team | | MCP SDK | Protocol implementation by Anthropic |