/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.
```bash
# 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 |
| **Forge/NeoForge patched source** | Build and browse the Minecraft source as modified by Forge/NeoForge (loader sources included), diff it against vanilla — fetched automatically via NeoFormRuntime |
| **Full-text search** | SQLite FTS5 indexes for fast BM25-ranked search across Minecraft and mod source |
26 tools across 5 categories — see [docs/tools.md](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. |
| **View Forge/NeoForge-modified Minecraft code** | `list_forge_versions` (optional) → `get_forge_source` — the patched tree (loader sources included, mojmap-only) builds automatically on first use via NeoFormRuntime (Java 21; first build takes minutes). Then `search_forge_code` / `compare_vanilla_vs_forge`, or any vanilla tool with the version key `1.21.1-neoforge-21.1.72`. |
| **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` |
```json
{
"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](#configuration)).
### Cache Contents
| Path | Contents |
| --- | --- |
| `jars/` | Client and server JARs |
| `mappings/` | Yarn, Mojmap, and Intermediary mapping files |
| `remapped/` | Remapped JARs |
| `decompiled///` | Decompiled Minecraft source |
| `decompiled-mods////` | Decompiled third-party mod source |
| `registry//` | 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:**
```bash
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](https://adoptium.net/) • 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](https://github.com/Vineflower/vineflower) |
| **tiny-remapper** | JAR remapping tool by [FabricMC](https://github.com/FabricMC) |
| **Yarn Mappings** | Community-maintained mappings by [FabricMC](https://fabricmc.net/) |
| **MCP SDK** | Protocol implementation by [Anthropic](https://github.com/modelcontextprotocol/typescript-sdk) |