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.

---

Quick Start

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

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

---

Features

Feature	Description
On-demand decompilation	Download, remap, and decompile any Minecraft version (1.14+) on first use — cached for instant access afterward
Multiple mapping namespaces	Yarn, Mojmap (official), Intermediary, and obfuscated — translate any symbol between them with find_mapping
Decompiled source access	Retrieve Java source for any Minecraft class with optional line-range filtering
Mod JAR analysis	Analyze Fabric, Quilt, Forge, and NeoForge mods — metadata, mixins, dependencies, entry points — and decompile them
Mixin & Access Widener validation	Validate Mixin annotations and .accesswidener files against decompiled source with error reporting and fix suggestions
Version diff	Class-level and AST-level diff between any two Minecraft versions — method signatures, field changes, breaking changes
Full-text search	SQLite FTS5 indexes for fast BM25-ranked search across Minecraft and mod source

20 tools across 4 categories — see docs/tools.md for the full reference.

---

Common Workflows

Workflow	Steps
First-time source access	Call get_minecraft_source — server downloads, remaps, and decompiles (~5 min first run). Subsequent requests for the same version return in ~50 ms from cache.
Analyze a third-party mod	analyze_mod_jar → remap_mod_jar → decompile_mod_jar → search_mod_code or index_mod + search_mod_indexed
Validate a Fabric mixin	analyze_mixin with your Java source or file path — validates targets, injection points, and method selectors against the decompiled MC version.
Find breaking changes between versions	compare_versions for a high-level overview, then compare_versions_detailed scoped to specific packages for full AST-level diffs.
Fast broad search	index_minecraft_version once, then search_indexed with FTS5 queries: entity AND damage, "onBlockBreak", tick*, BlockEntity NOT render.
Translate obfuscated names	find_mapping with sourceMapping: "official" to look up the Yarn or Mojmap equivalent for any class, method, or field.

---

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
Tests	npm test

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