@mcdxai/minecraft-dev-mcp
v1.0.0TypeScript
MCP server for Minecraft mod development - decompile, remap, and explore Minecraft source code
0/weekUpdated 1 months agoMITUnpacked: 852.9 KB
Published by GhostTypes
npm install @mcdxai/minecraft-dev-mcpMinecraft 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 -versionInstall: Adoptium or Oracle JDK |
Installation
| Method | Instructions |
|---|---|
| NPM (Recommended) |
npm install -g @minecraft-dev/mcp-server |
| From Source |
git clone https://github.com/MCDxAI/minecraft-dev-mcp.git |
Quick Start
1. Configure Claude Desktop
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
``
json
{
"mcpServers": {
"minecraft-dev": {
"command": "minecraft-dev-mcp"
}
}
}
`
Source Installation
`json
{
"mcpServers": {
"minecraft-dev": {
"command": "node",
"args": ["/path/to/minecraft-dev-mcp/dist/index.js"]
}
}
}
`
2. Restart Claude Desktop
Restart Claude Desktop to load the MCP server.
3. 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
`json
{
"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
`json
{
"version": "1.21.10",
"mapping": "yarn"
}
`
list_minecraft_versions
List available and cached Minecraft versions.
Returns
`json
{
"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
`json
{
"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
`json
{
"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
`json
{
"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
`json
{
"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
`json
{
"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
`json
{
"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
`json
{
"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
`json
{
"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
`json
{
"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
`json
{
"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
`json
{
"className": "Entity"
}
`
search_documentation
Search for documentation across all Minecraft/Fabric topics.
Parameter
Type
Description
query
string
Search query
Example
`json
{
"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
`json
{
"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
`json
{
"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 FoundJava 17+ is required but not found |
1. Install Java 17+ from Adoptium 2. Verify: java -version shows 17 or higher3. Ensure Java is in your PATH |
Decompilation FailsDecompilation failed: ... |
1. Check disk space (need ~500 MB per version) 2. Check logs: %APPDATA%\minecraft-dev-mcp\minecraft-dev-mcp.log3. Try force re-decompile: { "force": true }4. Clear cache and retry |
Mappings Not AvailableYarn 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 |
| Run Tests | npm test |
| Type Check | npm run typecheck |
| Lint | npm run lintnpm run lint:fix |
| Development Mode | npm run dev |
License
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
Built with ❤️ for the Minecraft modding community