@MCDxAI/minecraft-dev-mcpPublic

Connectors#Claude Code #Any agent#Coding #Research

MCP server for Minecraft mod development

Minecraft Dev MCP gives agents direct access to Minecraft source, mappings, and mod JAR analysis. It runs over stdio or HTTP and caches downloaded jars, mappings, decompiled source, and search indexes for reuse across sessions.

38 stars•10 forks•TypeScript•Updated 1mo ago

Who it's for

Builders who want their agent to inspect Minecraft code, compare versions, and analyze mods without leaving the workflow.

What it delivers

You can ask your agent to decompile, search, remap, and validate Minecraft code instead of doing that work by hand.

What it does

On-demand decompilation

Downloads, remaps, and decompiles Minecraft versions on first use, then serves cached source later.

Multiple mapping namespaces

Translates names across Yarn, Mojmap, Intermediary, and obfuscated mappings with `find_mapping`.

Mod JAR analysis

Inspects Fabric, Quilt, Forge, and NeoForge mods for metadata, mixins, dependencies, entry points, and source.

Mixin and access file validation

Checks Mixin annotations, Fabric access wideners, and Forge or NeoForge access transformers against real bytecode.

Version diff and search

Compares Minecraft versions and builds full-text search indexes for fast code lookup.

Standalone CLI

Provides `minecraft-dev-cli` for scripts and automation without an MCP client.

How to get it

1For clients or editors that connect over HTTP instead of stdio, start the server in HTTP…
```
minecraft-dev-mcp --http --port 3000
```

2A standalone CLI (minecraft-dev-cli) invokes the same tools directly — no MCP client…

# 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

3Build from source

git clone https://github.com/MCDxAI/minecraft-dev-mcp.git
cd minecraft-dev-mcp
npm install
npm run build

README

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

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

Files in the repo

Repository payload•23 top-level entries

__tests__— Tests
.claude— Claude Code skills, agents, commands, hooks
.github— GitHub workflows and templates
ai_reference— 1 item
docs— Documentation
skills— The skills, one folder each
src— Source code
tools— 2 items
.gitattributes
.gitignore
.mcp.json— MCP servers this repo connects to
AGENTS.md— Agent instructions for using this repository.
biome.json
CHANGELOG.md
CLAUDE.md— Claude-specific guidance and repository instructions.
LICENSE— License
package-lock.json
package.json— Node package: install with npm
README.md— The README
tsconfig.json
vitest.config.ts
vitest.manual.config.ts
vitest.mojmap.config.ts

Discussion (0)

Ask about usage, or say what you built with it

No comments yet. Be the first to say what this is good for.

More connectors

koala73/worldmonitorConnectors

Real-time global intelligence dashboard. AI-powered news aggregation, geopolitical monitoring, and infrastructure tracking in a unified situational awareness interface

86k

DeusData/codebase-memory-mcpConnectors

High-performance code intelligence MCP server. Indexes codebases into a persistent knowledge graph — average repo in milliseconds. 158 languages, sub-ms queries, 99% fewer tokens. Single static binary, zero dependencies.

43k

lidge-jun/opencodexConnectors

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM (Claude, Gemini, Grok, DeepSeek, Ollama…) with Codex CLI, App, SDK, and Claude Code

14k

okf-memory/

okf-agent-memory

okf-memory/okf-agent-memoryConnectors

Git-native persistent memory for AI coding agents. Implements Google OKF v0.2 with sub-300µs in-memory BM25 search, embedded MCP server, and progressive disclosure. Slashes token bloat by 80% with zero external databases or dependencies. Built in pure Go.

547

tirth8205/

code-review-graph

tirth8205/code-review-graphConnectors

Local-first code intelligence graph for MCP and CLI. Builds a persistent map of your codebase so AI coding tools read only what matters, with benchmarked context reductions on reviews and large-repo workflows.

31k

2akouwu/

reverify

2akouwu/reverifyConnectors

Stop your AI from making things up — it proposes, deterministic tools decide, every claim checked against ground truth with evidence. Grounded facts and context survive resets. Reverse engineering is the proving ground. MCP server + CLI.

1.1k