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