Minecraft Dev MCP Server

A comprehensive Model Context Protocol (MCP) server that enables AI agents and agentic CLIs (Claude Code, OpenAI Codex, etc.) to work seamlessly with Minecraft mod development. Provides decompilation, mapping translation (Yarn, Mojmap, Intermediary), mod analysis, mixin validation, version comparison, and deobfuscated source code access. Built with full WSL compatibility to support agentic tools running in WSL on Windows (like Codex) and native Windows environments (like Claude Code).

Core Capabilities

Feature	Description
Automatic Decompilation	Download, remap, and decompile any Minecraft version (1.14+)
Multiple Mapping Types	Support for Yarn, Mojmap (official), Intermediary, and obfuscated mappings
Smart Caching	Central cache system avoids re-downloading/re-decompiling
Source Code Access	Get decompiled Java source for any Minecraft class with full-text search
Registry Data	Extract block, item, entity, and other registry information
Mod Analysis	Remap, validate mixins, analyze access wideners, and extract mod metadata
Version Comparison	Compare Minecraft versions with class-level and AST-level diff analysis
Documentation Access	Search and access Minecraft/Fabric documentation and usage hints
Production-Grade Tools	Uses Vineflower decompiler, tiny-remapper, and SQLite FTS5 indexing

Prerequisites

Requirement	Details
Node.js 18+	Download Node.js
Java 17+	Required for decompilation tools Check: java -version Install: Adoptium or Oracle JDK

Installation

Method	Instructions
NPM (Recommended)	npm install -g @mcdxai/minecraft-dev-mcp
From Source	git clone https://github.com/MCDxAI/minecraft-dev-mcp.git cd minecraft-dev-mcp npm install npm run build

Quick Start

Claude Desktop Setup

Add to your Claude Desktop config 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)

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

Source Installation

{
  "mcpServers": {
    "minecraft-dev": {
      "command": "node",
      "args": ["/path/to/minecraft-dev-mcp/dist/index.js"]
    }
  }
}

Restart Claude Desktop to load the MCP server.

Claude Code Setup

Add to .claude/settings.local.json in your project:

Global Installation

npm install -g @mcdxai/minecraft-dev-mcp

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

NPX (No Installation)

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

The MCP server will be available immediately in Claude Code.

Start Using

In Claude Desktop, you can now ask questions like:

Category	Example Query
Source Access	"Show me the Entity class from Minecraft 1.21.10 using Yarn mappings"
Decompilation	"Decompile Minecraft 1.21.10 with Mojmap"
Registry Data	"What blocks are registered in Minecraft 1.21.10?"
Code Search	"Search for all methods containing 'onBlockBreak' in 1.21.10"
Version Diff	"Compare Minecraft 1.21.10 and 1.21.11 to find breaking changes"
Mod Analysis	"Analyze the meteor-client.jar file and show me its dependencies"
Mixin Validation	"Validate this mixin code against Minecraft 1.21.10"
Mapping Lookup	"Convert the obfuscated class 'abc' to Yarn names for 1.21.10"

Available Tools

16 powerful tools organized into three capability tiers

Phase	Tools	Description
Phase 1: Core Decompilation	4 tools	Essential decompilation, source access, version management, and registry data
Phase 2: Advanced Analysis	11 tools	Mod JAR remapping, mapping lookups, code search, version comparison, mixin/access widener validation, indexing, and documentation
Phase 3: Mod Analysis	1 tool	Comprehensive third-party mod JAR analysis for Fabric, Quilt, Forge, and NeoForge

Phase 1: Core Decompilation Tools

get_minecraft_source

Get decompiled source code for a specific Minecraft class.

Parameter	Type	Description
version	string	Minecraft version (e.g., "1.21.10")
className	string	Fully qualified class name (e.g., "net.minecraft.world.entity.Entity")
mapping	"yarn" | "mojmap"	Mapping type to use

Example

{
  "version": "1.21.10",
  "className": "net.minecraft.world.entity.Entity",
  "mapping": "yarn"
}

decompile_minecraft_version

Decompile an entire Minecraft version (runs once, then cached).

Parameter	Type	Description
version	string	Minecraft version
mapping	"yarn" | "mojmap"	Mapping type
force	boolean (optional)	Force re-decompilation

Example

{
  "version": "1.21.10",
  "mapping": "yarn"
}

list_minecraft_versions

List available and cached Minecraft versions.

Returns

{
  "cached": ["1.21.10"],
  "available": ["1.21.10", "1.21.9", "..."],
  "total_available": 800
}

get_registry_data

Get Minecraft registry data (blocks, items, entities, etc.).

Parameter	Type	Description
version	string	Minecraft version
registry	string (optional)	Specific registry (e.g., "blocks", "items", "entities")

Example

{
  "version": "1.21.10",
  "registry": "blocks"
}

Phase 2: Advanced Analysis Tools

remap_mod_jar

Remap Fabric mod JARs from intermediary to human-readable mappings.

Parameter	Type	Description
inputJar	string	Path to input mod JAR (WSL or Windows path)
outputJar	string	Path for output remapped JAR (WSL or Windows path)
mcVersion	string	Minecraft version the mod is for
toMapping	"yarn" | "mojmap"	Target mapping type

Example

{
  "inputJar": "/mnt/c/mods/mymod.jar",
  "outputJar": "/mnt/c/mods/mymod-remapped.jar",
  "mcVersion": "1.21.10",
  "toMapping": "yarn"
}

find_mapping

Look up symbol mappings between different mapping systems.

Parameter	Type	Description
symbol	string	Symbol to look up (class, method, or field name)
version	string	Minecraft version
sourceMapping	"official" | "intermediary" | "yarn" | "mojmap"	Source mapping type
targetMapping	"official" | "intermediary" | "yarn" | "mojmap"	Target mapping type

Example

{
  "symbol": "Entity",
  "version": "1.21.10",
  "sourceMapping": "yarn",
  "targetMapping": "mojmap"
}

search_minecraft_code

Search decompiled Minecraft source code using regex patterns.

Parameter	Type	Description
version	string	Minecraft version
query	string	Search query (regex pattern or literal)
searchType	"class" | "method" | "field" | "content" | "all"	Type of search to perform
mapping	"yarn" | "mojmap"	Mapping type
limit	number (optional)	Maximum results (default: 50)

Example

{
  "version": "1.21.10",
  "query": "onBlockBreak",
  "searchType": "method",
  "mapping": "yarn",
  "limit": 20
}

compare_versions

Compare two Minecraft versions to find differences.

Parameter	Type	Description
fromVersion	string	Source Minecraft version
toVersion	string	Target Minecraft version
mapping	"yarn" | "mojmap"	Mapping type to use
category	"classes" | "registry" | "all" (optional)	What to compare (default: all)

Example

{
  "fromVersion": "1.21.10",
  "toVersion": "1.21.11",
  "mapping": "yarn",
  "category": "all"
}

analyze_mixin

Analyze and validate Mixin code against Minecraft source.

Parameter	Type	Description
source	string	Mixin source code or path to JAR/directory (WSL or Windows)
mcVersion	string	Minecraft version to validate against
mapping	"yarn" | "mojmap" (optional)	Mapping type (default: yarn)

Example

{
  "source": "/path/to/MyMixin.java",
  "mcVersion": "1.21.10",
  "mapping": "yarn"
}

validate_access_widener

Validate Fabric Access Widener files against Minecraft source.

Parameter	Type	Description
content	string	Access widener content or path to .accesswidener file
mcVersion	string	Minecraft version to validate against
mapping	"yarn" | "mojmap" (optional)	Mapping type (default: yarn)

Example

{
  "content": "/path/to/mymod.accesswidener",
  "mcVersion": "1.21.10"
}

compare_versions_detailed

Compare versions with detailed AST-level analysis.

Parameter	Type	Description
fromVersion	string	Source Minecraft version
toVersion	string	Target Minecraft version
mapping	"yarn" | "mojmap"	Mapping type to use
packages	string[] (optional)	Specific packages to compare
maxClasses	number (optional)	Maximum classes (default: 1000)

Example

{
  "fromVersion": "1.21.10",
  "toVersion": "1.21.11",
  "mapping": "yarn",
  "packages": ["net.minecraft.entity"]
}

index_minecraft_version

Create a full-text search index for fast searching.

Parameter	Type	Description
version	string	Minecraft version to index
mapping	"yarn" | "mojmap"	Mapping type

Example

{
  "version": "1.21.10",
  "mapping": "yarn"
}

search_indexed

Fast full-text search using pre-built index (requires index_minecraft_version first).

Parameter	Type	Description
query	string	Search query (supports FTS5 syntax: AND, OR, NOT, "phrase", prefix*)
version	string	Minecraft version
mapping	"yarn" | "mojmap"	Mapping type
types	("class" | "method" | "field")[] (optional)	Entry types to search
limit	number (optional)	Maximum results (default: 100)

Example

{
  "query": "entity AND damage",
  "version": "1.21.10",
  "mapping": "yarn",
  "types": ["method"],
  "limit": 50
}

get_documentation

Get documentation for Minecraft classes and concepts.

Parameter	Type	Description
className	string	Class name to get documentation for

Example

{
  "className": "Entity"
}

search_documentation

Search for documentation across all Minecraft/Fabric topics.

Parameter	Type	Description
query	string	Search query

Example

{
  "query": "block entity"
}

Phase 3: Mod Analysis Tools

analyze_mod_jar

Analyze third-party mod JARs to extract comprehensive metadata.

Parameter	Type	Description
jarPath	string	Local path to mod JAR file (WSL or Windows path)
includeAllClasses	boolean (optional)	Include full class list (default: false)
includeRawMetadata	boolean (optional)	Include raw metadata files (default: false)

Supports: Fabric, Quilt, Forge, and NeoForge mods

Returns: Mod ID, version, dependencies, entry points, mixin configurations, class statistics, and more

Example

{
  "jarPath": "C:\\mods\\meteor-client.jar",
  "includeAllClasses": false,
  "includeRawMetadata": true
}

Architecture

Cache Structure

All data is cached in a platform-specific directory:

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

Cache Layout

Directory	Contents
jars/	Downloaded Minecraft client JARs
mappings/	Yarn/Mojmap mapping files
remapped/	Remapped JARs (intermediary → named)
decompiled/	Decompiled source code └── 1.21.10/     ├── yarn/     └── mojmap/
registry/	Registry data (blocks, items, etc.)
search-index/	SQLite FTS5 full-text search indexes └── 1.21.10-yarn.db
resources/	Downloaded tools (Vineflower, tiny-remapper)
cache.db	SQLite metadata database
minecraft-dev-mcp.log	Log file

Cache Size

Component	Size
Minecraft Version	~400-500 MB per version (JAR + mappings + decompiled source)
Search Index	~50-100 MB per index (optional, created on-demand with index_minecraft_version)
Decompiler Tools	~1 MB for Vineflower + tiny-remapper (one-time download)

Technology Stack

Component	Technology
MCP SDK	@modelcontextprotocol/sdk 1.0.4
Decompiler	Vineflower 1.11.2 (Java 17+ decompiler)
Remapper	tiny-remapper 0.10.3 (FabricMC's bytecode remapper)
Yarn Mappings	FabricMC Yarn (community mappings)
Mojmap	Official Mojang Mappings
Database	better-sqlite3 (metadata caching & FTS5 indexing)
JAR Parsing	adm-zip (mod JAR analysis & bytecode extraction)
Schema Validation	Zod (tool input validation)

Version Support

Supported Minecraft Versions: 1.14+ (any version with available mappings)

Version Range	Yarn Mappings	Mojmap	Notes
1.14 - 1.21.11	✅ Full Support	✅ Full Support	Obfuscated versions requiring remapping
26.1+	❌ Not Available	✅ Official Names	Deobfuscated by Mojang (no remapping needed)

Important Notes

Topic	Details
Last Obfuscated Version	1.21.11 is the last obfuscated Minecraft version
Yarn Mapping Status	Discontinued after 1.21.11 (obfuscation removal makes them unnecessary)
Future Versions	Versions 26.1+ ship with official deobfuscated code
Tested Versions	1.19.4, 1.20.1, 1.21.10, 1.21.11 (latest)

Configuration

Environment Variables

Variable	Description
CACHE_DIR	Override cache directory location
LOG_LEVEL	Set logging level (DEBUG, INFO, WARN, ERROR)

Example

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

Workflow Examples

Example 1: First-Time Decompilation

When you request source code for the first time:

Step	Action	Time
1	Download Minecraft 1.21.10 client JAR (~50 MB)	~30s
2	Download Yarn mappings (~5 MB)	~5s
3	Remap JAR from obfuscated to Yarn names	~2 min
4	Decompile all classes with Vineflower	~3 min
5	Return requested class source code	Instant
Total	~5 minutes first time

Example 2: Subsequent Requests (Cached)

When you request another class from the same version:

Step	Action	Time
1	Read from cached decompiled source	~50ms
2	Return class source code	Instant
Total	~50ms (instant)

Troubleshooting

Issue	Solution
Java Not Found Java 17+ is required but not found	1. Install Java 17+ from Adoptium 2. Verify: java -version shows 17 or higher 3. Ensure Java is in your PATH
Decompilation Fails Decompilation failed: ...	1. Check disk space (need ~500 MB per version) 2. Check logs: %APPDATA%\minecraft-dev-mcp\minecraft-dev-mcp.log 3. Try force re-decompile: { "force": true } 4. Clear cache and retry
Mappings Not Available Yarn mappings not available for version X.X.X	Yarn mappings support 1.14-1.21.11 (discontinued after 1.21.11) Mojmap supports 1.14.4+ For versions 26.1+, use Mojmap (Minecraft is now deobfuscated by default)

Development

Task	Command
Build from Source	git clone https://github.com/MCDxAI/minecraft-dev-mcp.git cd minecraft-dev-mcp npm install npm run build
Run Tests	npm test
Type Check	npm run typecheck
Lint	npm run lint npm run lint:fix
Development Mode	npm run dev

License

MIT License - see LICENSE file for details

Credits

Project	Link
Vineflower	Modern Java decompiler by Vineflower Team
tiny-remapper	JAR remapping tool by FabricMC
Yarn Mappings	Community mappings by FabricMC
MCP SDK	Protocol implementation by Anthropic

Support

Resource	Link
Issues	GitHub Issues
Discussions	GitHub Discussions
Documentation	ARCHITECTURE.md

Built with ❤️ for the Minecraft modding community