Skip to content

MCDxAI/minecraft-dev-mcp

BranchesTags

Repository files navigation

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

About

Model Context Protocol server for Minecraft Development

Topics

java-decompiler minecraft-mod mojmap model-context-protocol yarn-mappings

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Contributors 2

Languages