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

HTTP Transport

For clients or editors that connect over HTTP instead of stdio, start the server in HTTP mode. It uses the MCP Streamable HTTP transport with per-session isolation.

Flag	Description
`--http`	Start with the Streamable HTTP transport instead of stdio
`--port <number>`	Port to listen on (default: `3000`) — also implies `--http`
`--host <address>`	Host to bind to (default: `127.0.0.1`)

minecraft-dev-mcp --http --port 3000

The MCP endpoint is http://<host>:<port>/mcp (POST to call, GET for the SSE stream, DELETE to end a session). Each client gets its own session, so multiple clients can connect concurrently.

Security: the default host 127.0.0.1 enables the SDK's DNS-rebinding protection automatically. Binding to a non-loopback host (e.g. --host 0.0.0.0) disables that protection — only do so on a trusted network, ideally behind a reverse proxy or auth.

CLI

A standalone CLI (minecraft-dev-cli) invokes the same tools directly — no MCP client required — for scripts, skills, and automation. Arguments are flags-only (--key value or --key=value) to avoid the JSON-quoting issues positional JSON arguments cause in PowerShell and other shells.

# List every tool with its parameters
minecraft-dev-cli list-tools

# Invoke a tool with flags
minecraft-dev-cli get_minecraft_source --version 1.21.10 --className net.minecraft.world.entity.Entity --mapping yarn

# Boolean / numeric / JSON values are coerced automatically
minecraft-dev-cli analyze_mod_jar --jarPath C:\mods\example.jar --includeAllClasses true

Output is always JSON: { "success": true, "tool": "...", "result": ... } on success, or { "success": false, "tool": "...", "error": "..." } with exit code 1 on failure. Run minecraft-dev-cli help for full usage.

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 & Access Transformer validation	Validate Mixin annotations, Fabric `.accesswidener` files, and Forge/NeoForge access transformer `.cfg` files with error reporting and fix suggestions. Access widener/transformer checks run against the game's real bytecode, catching inherited members, record constructors, inner-class reachability, and conflicts across multiple AT files
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

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

Cache Location

Downloaded JARs, mappings, decompiled source, and search databases live in a platform-specific cache directory shared across all workspaces (~400–500 MB per Minecraft version).

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

Delete the directory to clear the cache — the server re-downloads anything missing on next use. To relocate the cache anywhere on disk, set the CACHE_DIR environment variable (see Configuration).

Cache Contents

Path	Contents
`jars/`	Client and server JARs
`mappings/`	Yarn, Mojmap, and Intermediary mapping files
`remapped/`	Remapped JARs
`decompiled/<version>/<mapping>/`	Decompiled Minecraft source
`decompiled-mods/<modId>/<modVersion>/<mapping>/`	Decompiled third-party mod source
`registry/<version>/`	Extracted registry data (blocks, items, entities)
`resources/`	Java tool JARs (VineFlower, tiny-remapper)
`cache.db`	SQLite metadata database
`search_index.db`	SQLite FTS5 full-text search index
`minecraft-dev-mcp.log`	Server log file

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