# @adhisang/minecraft-modding-mcp [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/adhi-jp/minecraft-modding-mcp  
**GitHub Stars:** 8  
**npm Downloads (last month):** 781  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/adhisang-minecraft-modding-mcp

## Description
MCP server for AI-assisted Minecraft modding: inspect decompiled source, resolve Mojang/Yarn/Intermediary mappings, diff versions, analyze Fabric/Forge/NeoForge mod JARs, and validate Mixin, Access Widener, and Access Transformer files.

## Tools
Capabilities this server exposes over MCP:

- **list-versions** — List available Minecraft versions from Mojang manifest and locally cached version jars. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **inspect-minecraft** — Top-level workflow tool for version discovery, artifact resolution, class inspection, source search, file reads, and file listings. Workspace subject.focus is a structured class/file/search object, never a string; task=auto dispatches from subject.kind and focus.kind.
- **analyze-symbol** — Top-level workflow tool for symbol existence, mapping, lifecycle, workspace analysis, and API overview. subject.kind='symbol' auto-detects class/field/method from the selector.
- **compare-minecraft** — Top-level workflow tool for version comparisons, class diffs, registry diffs, and migration overviews.
- **analyze-mod** — Top-level workflow tool for mod metadata inspection, decompile/search flows, class source, bytecode-only class member reads, and safe remap previews/applies.
- **validate-project** — Top-level workflow tool for project summary, direct mixin validation, and access widener/access transformer validation.
- **manage-cache** — Top-level workflow tool for cache summaries, listing, verification, previewed mutation, and explicit apply operations.
- **verify-mixin-target** — Single-call probe: does this target owner / member exist and which @Shadow / @Accessor / @Invoker should the mixin use? Reuses target.kind workspace/version/coordinate/dependency/jar.
- **batch-class-source** — Batch get-class-source for many classes sharing one resolved artifact; returns per-entry status plus aggregate summary. Not read-only: per-entry outputFile writes to disk.
- **batch-class-members** — Batch get-class-members for many classes sharing one resolved artifact; returns per-entry status plus aggregate summary.
- **batch-symbol-exists** — Batch check-symbol-exists for many symbols against one shared Minecraft version (target.kind=version or workspace only).
- **batch-mappings** — Batch find-mapping: resolve many symbols across mapping namespaces with one shared Minecraft version.
- **resolve-artifact** — Resolve a source artifact and return artifact metadata. For target.kind=jar, only <basename>-sources.jar is auto-adopted. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **find-class** — Resolve a simple or qualified class name to fully-qualified class names within an artifact. Use this before get-class-source when you only have a simple name. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **get-class-source** — Get Java source for a class. Default mode=metadata returns a symbol outline only; pass mode=snippet or mode=full to read source text. Not read-only: outputFile writes to disk. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **get-class-members** — Get fields/methods/constructors for one class from binary bytecode. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **search-class-source** — Search indexed class source files for one artifact with symbol/text/path intent and compact hit output. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **get-artifact-file** — Get full source file content by artifactId and file path. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **list-artifact-files** — List source file paths in an artifact with optional prefix filter and cursor-based pagination. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **trace-symbol-lifecycle** — Trace which Minecraft versions contain a specific class method and report first/last seen versions. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **diff-class-signatures** — Compare one class signature between two Minecraft versions and report added/removed/modified constructors, methods, and fields. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **find-mapping** — Find symbol mapping candidates between namespaces using structured symbol inputs for a specific Minecraft version. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **resolve-method-mapping-exact** — Strict variant of find-mapping(kind=method, signatureMode=exact): requires a COMPLETE descriptor projection and returns mapping_unavailable when any descriptor class reference cannot be projected. Prefer find-mapping unless you need that guarantee. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **get-class-api-matrix** — List class/member API rows across obfuscated/mojang/intermediary/yarn mappings for one class and Minecraft version. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **resolve-workspace-symbol** — Resolve class/field/method names as seen at compile time for a workspace by reading Gradle Loom mapping settings. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **check-symbol-exists** — Check whether a class/field/method symbol exists in a specific mapping namespace for one Minecraft version. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **nbt-to-json** — Decode Java Edition NBT binary payload (base64) into typed JSON.
- **nbt-apply-json-patch** — Apply RFC6902 add/remove/replace/test operations to typed NBT JSON.
- **json-to-nbt** — Encode typed NBT JSON to Java Edition NBT binary payload (base64).
- **index-artifact** — Rebuild indexed files/symbols metadata for an artifact addressed by artifactId or target. A new target is resolved and ingested first; force rebuilds an existing index. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **get-runtime-metrics** — Get runtime service counters and latency snapshots for cache/search/index diagnostics.
- **validate-mixin** — Validate Mixin source against Minecraft bytecode signatures for a given version. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **validate-access-widener** — Validate Access Widener file entries against Minecraft bytecode signatures for a given version. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **validate-access-transformer** — Validate Access Transformer file entries against Minecraft bytecode signatures for a given version. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **analyze-mod-jar** — Analyze a Minecraft mod JAR to extract loader type, metadata, entrypoints, mixins, and dependencies. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **get-registry-data** — Get Minecraft registry data (blocks, items, biomes, etc.) for a specific version by running the server data generator.
- **compare-versions** — Compare two Minecraft versions to find added/removed classes and registry entry changes. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **decompile-mod-jar** — Decompile a Minecraft mod JAR using Vineflower and list available classes, or view a specific class source. Builds on analyze-mod-jar. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **get-mod-class-source** — Get decompiled source code for a specific class in a mod JAR. The mod JAR will be decompiled if not already cached. Not read-only: outputFile writes the source to disk. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **search-mod-source** — Search through decompiled mod JAR source code by class name, method, field, or content pattern. The mod JAR will be decompiled automatically if not already cached. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.
- **remap-mod-jar** — Remap a Fabric mod JAR from intermediary to yarn/mojang names. Requires Java to be installed. Expert tool: prefer the entry tools (inspect-minecraft, analyze-symbol, compare-minecraft, analyze-mod, validate-project) first.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "minecraft-modding-mcp": {
    "command": "npx",
    "args": ["-y","@adhisang/minecraft-modding-mcp"]
  }
}
```

## Documentation

## What @adhisang/minecraft-modding-mcp MCP server does

@adhisang/minecraft-modding-mcp MCP server provides tools for investigating Minecraft internals and mod projects from an MCP-compatible client. It can inspect version metadata, artifacts, indexed files, classes, source text, and workspace symbols. Mapping-aware operations cover the `obfuscated`, `mojang`, `intermediary`, and `yarn` namespaces.

The server also supports cross-version analysis. Agents can check whether classes, fields, or methods exist, trace a symbol across releases, compare class signatures, review registry changes, and produce migration-oriented summaries. For mod development, it reads metadata and dependencies from Fabric, Forge, and NeoForge JARs, examines entrypoints and Mixin configuration, searches decompiled code, and previews or applies remappings.

NBT workflows are included for Java Edition binary data. Typed JSON can be encoded to NBT, decoded from NBT, or modified with RFC 6902 patches. Project-oriented checks cover Mixin source, `.accesswidener` files, and Forge or NeoForge Access Transformer files.

## How it works

@adhisang/minecraft-modding-mcp MCP server runs locally over stdio and exposes workflow-oriented entry points alongside more specialized tools. The main workflows are `inspect-minecraft`, `analyze-symbol`, `compare-minecraft`, `analyze-mod`, `validate-project`, and `manage-cache`. Additional tools handle artifact resolution, class lookup, source retrieval, mapping queries, lifecycle tracing, version listing, indexing, NBT conversion, and mod-JAR inspection.

A SQLite-backed cache stores indexed and downloaded data. The server can expose versions, artifact metadata, mappings, and class source through MCP resources. Source operations may resolve an artifact from a Minecraft version, a JAR path, or Maven coordinates; workspace-aware operations can use a Gradle project and its compile-visible symbols.

## Setup and configuration

Install Node.js 22.13.0 or newer, then run `npx -y @adhisang/minecraft-modding-mcp` as the MCP server command. The same command can be registered with Claude Desktop, Claude Code, VS Code, Codex CLI, Gemini CLI, or another MCP-capable client. The server accepts both newline-delimited and `Content-Length` stdio framing.

Java 17 or newer on `PATH` is required for workflows that need decompilation or remapping, including some Minecraft source lookups and mod-JAR decompilation. Registry generation and registry comparisons may require the Java version expected by the selected Minecraft release. If automatic helper-JAR downloads are unavailable, configure `MCP_VINEFLOWER_JAR_PATH` and `MCP_TINY_REMAPPER_JAR_PATH`. `MCP_CACHE_DIR` changes the cache location, while `MCP_MAPPING_SOURCE_PRIORITY` can select mapping-source priority.

## Tools and capabilities

- Inspect versions, artifacts, classes, files, source, and workspace context.
- Resolve mappings, exact method mappings, workspace symbols, and API matrices.
- Find classes, including classes inside nested JARs, and read members from bytecode.
- Search indexed Minecraft source or decompiled mod source.
- Compare releases, class signatures, registries, and symbol lifecycles.
- Analyze mod metadata, dependencies, entrypoints, Mixins, access transformers, and remap operations.
- Validate projects, manage cache cleanup, and convert or patch NBT data.

## Limitations and notes

The process serves one MCP protocol era selected from the client’s first signal. Source and cache-backed calls may need a `gradleUserHome` value when a build uses a non-default Gradle User Home. The server searches supported Loom cache locations rather than accepting arbitrary Loom cache directories. Full source reads are subject to byte limits, and paginated artifact-file listings use cursors.

_Full upstream README: https://allmcps.com/mcp/adhisang-minecraft-modding-mcp/readme_