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.

20 tools spanning decompilation, mapping translation, mod analysis, mixin validation, version comparison, and full-text search — with full WSL and Windows path support.

Capabilities

| Feature | Description | | --- | --- | | Automatic Decompilation | Download, remap, and decompile any Minecraft version (1.14+) on-demand with persistent smart caching | | Multiple Mapping Systems | Full support for Yarn, Mojmap (official), Intermediary, and obfuscated (official) namespaces | | Source Code Access | Retrieve decompiled Java source for any Minecraft class with optional line-range filtering | | Registry Data | Extract block, item, entity, and other game registry data from any supported version | | Mod JAR Analysis | Analyze Fabric, Quilt, Forge, and NeoForge mods — metadata, mixins, dependencies, entry points, class statistics | | Mod Decompilation | Decompile third-party mod JARs to readable Java source with full regex and FTS5 search support | | Mixin Validation | Parse and validate Mixin annotations against Minecraft source — validates targets, injection points, and suggests fixes | | Access Widener Validation | Validate .accesswidener files against decompiled source with error reporting and similarity suggestions | | Version Comparison | Class-level and AST-level diff analysis between Minecraft versions — method signatures, field changes, breaking changes | | Full-Text Search | SQLite FTS5 indexes for fast searching across Minecraft and mod source with BM25 ranking | | Mapping Translation | Translate any symbol between official, intermediary, Yarn, and Mojmap namespaces | | Unobfuscated Version Support | Native support for Minecraft 26.1+ which ships with deobfuscated class names | | WSL Compatibility | Accepts both WSL (/mnt/c/...) and Windows (C:\...) paths throughout all tools |

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 |

Quick Start

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"
    }
  }
}

Tools Reference

20 tools organized by functionality.

Source Code (6 tools)

Decompile, browse, and search Minecraft source code.

| Tool | Description | Parameters | | --- | --- | --- | | list_minecraft_versions | List all versions available from Mojang and which are already cached locally. | None | | decompile_minecraft_version | Decompile an entire Minecraft version. Downloads the client JAR, remaps it, and decompiles all classes with VineFlower. Subsequent calls use cached results. | version, mapping • Optional: force (re-decompile) | | get_minecraft_source | Get decompiled Java source for a specific Minecraft class. Downloads, remaps, and decompiles automatically on first use; subsequent requests are instant from cache. | version, className, mapping (yarn|mojmap) • Optional: startLine, endLine, maxLines | | search_minecraft_code | Regex search across decompiled Minecraft source by class name, method name, field name, or file content. | version, query, searchType (class|method|field|content|all), mapping • Optional: limit | | index_minecraft_version | Build a SQLite FTS5 full-text search index for decompiled Minecraft source. Required before using search_indexed. | version, mapping | | search_indexed | Fast full-text search on a pre-built index using FTS5 syntax. Significantly faster than search_minecraft_code for broad queries. Supports AND, OR, NOT, phrase matching, and prefix wildcards. | query, version, mapping • Optional: types (class|method|field), limit |

Mappings & Registry (3 tools)

Translate names between namespaces and explore game data.

| Tool | Description | Parameters | | --- | --- | --- | | find_mapping | Translate a class, method, or field name between any two mapping namespaces (official, intermediary, yarn, mojmap). | symbol, version, sourceMapping, targetMapping | | remap_mod_jar | Remap a Fabric mod JAR from intermediary to human-readable Yarn or Mojmap names. Accepts WSL and Windows paths. Minecraft version is auto-detected from mod metadata if not provided. | inputJar, outputJar, toMapping • Optional: mcVersion | | get_registry_data | Extract registry data (blocks, items, entities, etc.) for a version by running Minecraft's built-in data generator. | version • Optional: registry (e.g., block, item, entity) |

Analysis & Validation (6 tools)

Compare versions, validate mod code, and browse documentation.

| Tool | Description | Parameters | | --- | --- | --- | | compare_versions | Compare two Minecraft versions to identify added and removed classes and registry entries. | fromVersion, toVersion, mapping • Optional: category (classes|registry|all) | | compare_versions_detailed | AST-level version comparison showing exact method signature changes, field type changes, and breaking API modifications. Can be scoped to specific packages. | fromVersion, toVersion, mapping • Optional: packages, maxClasses | | analyze_mixin | Parse and validate Mixin code against Minecraft source. Validates target classes, injection methods, and annotation syntax. Provides similarity suggestions on failures. | source (Java code or file path), mcVersion • Optional: mapping | | validate_access_widener | Validate a Fabric Access Widener file against Minecraft source. Checks all class, method, and field targets exist and flags invalid entries. | content (file content or path), mcVersion • Optional: mapping | | get_documentation | Get documentation links and usage hints for a Minecraft or Fabric class. Links to Fabric Wiki and Minecraft Wiki. | className | | search_documentation | Search across all known Minecraft and Fabric documentation topics. | query |

Mod Analysis (5 tools)

Analyze and decompile third-party mod JARs.

| Tool | Description | Parameters | | --- | --- | --- | | analyze_mod_jar | Analyze a third-party mod JAR without decompiling. Extracts mod ID, version, dependencies, entry points, mixin configs, and class statistics. Supports Fabric, Quilt, Forge, and NeoForge. | jarPath • Optional: includeAllClasses, includeRawMetadata | | decompile_mod_jar | Decompile a mod JAR to readable Java source. Accepts original (intermediary) or remapped JARs. Mod ID and version are auto-detected from metadata. | jarPath, mapping • Optional: modId, modVersion | | search_mod_code | Regex search in decompiled mod source by class, method, field, or content. | modId, modVersion, query, searchType, mapping • Optional: limit | | index_mod | Build a SQLite FTS5 full-text search index for decompiled mod source. Required before using search_mod_indexed. | modId, modVersion, mapping • Optional: force | | search_mod_indexed | Fast FTS5 search on a pre-built mod index. Supports AND, OR, NOT, phrase matching, and prefix wildcards. | query, modId, modVersion, mapping • Optional: types, limit |

Common Workflows

| Workflow | Steps | | --- | --- | | First-time source access | Call get_minecraft_source → server downloads client JAR (~50 MB), mappings (~5 MB), remaps (~2 min), decompiles with VineFlower (~3 min), returns source. Total: ~5 min first run. Subsequent requests for any class from the same version return in ~50ms from cache. | | Analyze a third-party mod | 1. analyze_mod_jar (no decompilation needed, returns metadata instantly) → 2. remap_mod_jar to translate from intermediary → 3. decompile_mod_jar → 4. search_mod_code or index_mod + search_mod_indexed | | Validate a Fabric mixin | analyze_mixin with your Java source or JAR path — validates target classes, method selectors, and injection types against the decompiled MC version. Returns errors and name suggestions. | | Find breaking changes between versions | compare_versions for a high-level class and registry overview, then compare_versions_detailed scoped to specific packages for full AST-level method and field diffs. | | Fast broad code search | index_minecraft_version once per version/mapping combination, then search_indexed with FTS5 queries: entity AND damage, "onBlockBreak", tick*, BlockEntity NOT render. | | Translate obfuscated names | find_mapping with sourceMapping: "official" and your obfuscated symbol to look up the equivalent Yarn or Mojmap name. Supports class, method, and field lookups. |

Architecture

Technology Stack

| Component | Technology | | --- | --- | | MCP SDK | @modelcontextprotocol/sdk 1.0.4 | | Decompiler | VineFlower 1.11.2 — modern Java 17+ decompiler with generics support | | Remapper | tiny-remapper 0.10.3 — FabricMC's multi-threaded bytecode remapper | | Yarn Mappings | FabricMC Yarn — community-maintained mappings | | Mojmap | Official Mojang mappings (available 1.14.4+) | | Database | better-sqlite3 11.7.0 — metadata caching and FTS5 full-text indexing | | JAR Parsing | adm-zip 0.5.16 — mod JAR analysis and bytecode scanning | | Schema Validation | Zod 3.24.1 — runtime validation for all tool inputs | | Language | TypeScript 5.7.2, ESM-only ("type": "module") | | Linter | Biome 1.9.4 | | Tests | Vitest 2.1.8 — 27 test files covering the full pipeline |

Remapping Strategy

Yarn mappings require a two-step remapping process due to how FabricMC's mapping system is structured:

| Step | From | To | Mapping File | | --- | --- | --- | --- | | 1 | Official (obfuscated) | Intermediary | intermediary.tiny | | 2 | Intermediary | Named (Yarn or Mojmap) | yarn.tiny or mojmap.tiny |

Intermediary provides stable, version-independent identifiers that bridge between obfuscated official names and human-readable Yarn/Mojmap names.

Cache Structure

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

| Path | Contents | | --- | --- | | jars/ | Downloaded Minecraft client and server JARs | | mappings/ | Yarn, Mojmap, and Intermediary mapping files in Tiny v2 format | | remapped/ | Remapped JARs (obfuscated → named) | | decompiled/{version}/{mapping}/ | Decompiled Minecraft Java source files | | decompiled-mods/{modId}/{modVersion}/{mapping}/ | Decompiled mod source files | | registry/{version}/ | Registry data extracted by Minecraft's data generator | | resources/ | VineFlower and tiny-remapper JARs (downloaded once) | | search_index.db | SQLite FTS5 indexes for Minecraft and mod source | | minecraft-dev-mcp.db | Metadata, job tracking, and cache state | | minecraft-dev-mcp.log | Server log file |

| Component | Approximate Size | | --- | --- | | Per Minecraft version | ~400–500 MB (JAR + mappings + remapped JAR + decompiled source) | | Per search index | ~50–100 MB (SQLite FTS5, created on-demand) | | Decompiler tools | ~1 MB (VineFlower + tiny-remapper, one-time download) |

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"
      }
    }
  }
}

Development

| Task | Command | | --- | --- | | Install dependencies | npm install | | Build | npm run build | | Dev mode (hot reload) | npm run dev | | Type check | npm run typecheck | | Lint | npm run lint | | Lint with autofix | npm run lint:fix | | Integration tests | npm test | | Full pipeline — 1.21.10 | npm run test:manual:1.21.10 | | Full pipeline — 1.20.1 | npm run test:manual:1.20.1 | | MCP stdio tests | npm run test:manual:mcp | | MCP Inspector | npm run inspect |

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 |

Built for the Minecraft modding community