@adhisang/minecraft-modding-mcp

English | 日本語

Note: This project is entirely vibe-coded — built with AI-assisted development without formal specs.

---

@adhisang/minecraft-modding-mcp is an MCP server for AI-assisted Minecraft modding workflows, built on the Model Context Protocol. Use it when an agent needs to inspect Minecraft source, resolve mappings, compare versions, analyze mod JARs, validate Mixin, Access Widener, or Access Transformer files, or work with NBT and registry data from an MCP client.

It runs over stdio and works with Claude Desktop, Claude Code, VS Code, Codex CLI, Gemini CLI, and other MCP-capable clients.

41 tools (6 entry + 35 expert) | 9 resources | 4 namespace mappings | SQLite-backed cache

Features

• Source exploration: browse, list, and search decompiled Minecraft source with line-level context
• Mapping-aware symbol work: convert class, field, and method names between obfuscated, mojang, intermediary, and yarn
• Version comparison: compare class signatures, registry entries, and migration-oriented summaries across Minecraft versions
• Mod JAR analysis: read Fabric, Forge, and NeoForge metadata, entrypoints, Mixin configs, dependencies, source, and remap previews
• Project validation: validate Mixin source, .accesswidener files, and Forge/NeoForge Access Transformer files against the target version
• NBT, registry, cache, and diagnostics: patch NBT payloads, inspect generated registry data, and manage cache/runtime state
• MCP resources: expose versions, class source, artifact metadata, and mappings through URI-based resources

Quick Start

Package Users

Requirements:

• Node.js 22+
• Java is only required for remap-mod-jar and decompile or remap flows that need Vineflower or tiny-remapper

Start the server locally:

npx -y @adhisang/minecraft-modding-mcp

Use this same command in MCP client configs. If automatic JAR downloads are blocked in your environment, set MCP_VINEFLOWER_JAR_PATH and MCP_TINY_REMAPPER_JAR_PATH there.

Client Setup

CLI clients can register the package command directly.

Claude Code:

claude mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp

OpenAI Codex CLI:

codex mcp add minecraft-modding -- npx -y @adhisang/minecraft-modding-mcp

Run claude mcp list or codex mcp list after registration to verify the server is available.

The stdio transport auto-detects newline-delimited and Content-Length framing, so the same server command works across Codex and standard MCP clients.

Claude Desktop

Add the following to your claude_desktop_config.json:

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

VS Code

Add the following to .vscode/mcp.json in your workspace:

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

Gemini CLI

Add the following to ~/.gemini/settings.json:

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

Then run:

/mcp list

Custom Environment

Pass environment variables to override defaults:

{
  "mcpServers": {
    "minecraft-modding": {
      "command": "npx",
      "args": ["-y", "@adhisang/minecraft-modding-mcp"],
      "env": {
        "MCP_CACHE_DIR": "/path/to/custom/cache",
        "MCP_MAPPING_SOURCE_PRIORITY": "maven-first"
      }
    }
  }
}

When a build used a non-default Gradle User Home, pass gradleUserHome on cache-backed source, mapping, validation, and workflow calls. The server treats it as a per-call Gradle User Home and searches <gradleUserHome>/loom-cache and <gradleUserHome>/caches/fabric-loom before the MCP process default. It does not accept arbitrary Loom cache directories.

Start Here

These six top-level workflow tools cover the common paths and return summary-first results. They are the best default starting points for agents and MCP clients.

All six return result.summary first and can include summary.nextActions when there is a clear follow-up step. Pick the tool from the table, then use the examples and reference docs for exact payloads.

| Tool | Start here for | | --- | --- | | inspect-minecraft | versions, artifacts, classes, files, and source search | | analyze-symbol | symbol existence checks, mapping conversion, lifecycle tracing, and workspace symbol resolution | | compare-minecraft | version-pair diffs, class diffs, registry diffs, and migration-oriented overviews | | analyze-mod | mod metadata, decompile/search flows, class source, bytecode member queries, and safe remap preview/apply | | validate-project | workspace summaries plus direct Mixin, Access Widener, and Access Transformer validation | | manage-cache | cache inventory, verification, and preview/apply cleanup workflows |

Workflow Notes

These notes cover high-frequency decisions during onboarding. For the full pitfall list, exact contracts, migration notes, and environment variables, see docs/tool-reference.md.

• search-class-source defaults to queryMode="auto" and keeps separator queries such as foo.bar, foo_bar, and foo$bar on the indexed path. Use queryMode="literal" for an explicit full substring scan.
• If you do not already have an artifact, prefer subject.kind="workspace" for inspect-minecraft instead of guessing artifact details. subject.focus is an object, not a string: use { "kind": "class", "className": "..." }, { "kind": "search", "query": "..." }, or { "kind": "file", "filePath": "..." }. task="auto" dispatches only from subject.kind and focus.kind; it is not a natural-language planner. Invalid string focus returns class/search/file exampleCalls, while missing artifact context keeps the requested task in a retryable suggestedCall.
• trace-symbol-lifecycle expects Class.method in symbol. Keep exact overload matching in the separate descriptor field.
• For unobfuscated releases such as 26.1+, check-symbol-exists and analyze-symbol task="exists" validate mojang lookups against runtime bytecode when no mapping graph exists, and return mapping_unavailable when the runtime JAR itself is unreachable.
• analyze-mod and validate-project require structured subject objects and canonical include groups; stale string-subject or domain-include payloads return ERR_INVALID_INPUT with a retryable suggestedCall.
• validate-project task="project-summary" propagates preferProjectVersion=true across discovered Mixin, Access Widener, and Access Transformer checks. If no version can be resolved from the request or gradle.properties, the summary returns recovery guidance instead of guessing.
• validate-mixin and validate-project keep mapping-health lightweight for obfuscated and mojang validation, avoiding full Tiny mapping graph loads unless intermediary or yarn namespaces are requested.
• validate-project task="project-summary" uses a lightweight artifact probe for tasks["minecraft.artifact.resolved"]; it does not decompile Minecraft or rebuild the source index just to report per-probe status. Set VALIDATE_PROJECT_TASKS_OFF=1 to omit the additive tasks field.
• validate-project has a supervisor-owned end-to-end deadline of 120 seconds, including queue time. Set MCP_VALIDATE_PROJECT_TIMEOUT_MS to an ASCII-decimal value from 10000 through 600000 to override it. A timeout returns ERR_TOOL_TIMEOUT; a running timeout restarts the isolated worker before queued calls resume, while a queue timeout leaves the current worker untouched.
• Queued calls resume only after the replacement worker completes initialization replay. If replacement startup or replay fails, queued tool calls terminate with ERR_WORKER_RESTART instead of waiting indefinitely. If unresolved process-tree cleanup fills the supervisor's two live-generation slots, new requests fail with the existing restart envelope and unavailable notifications are warning-dropped until cleanup or reconnect. On POSIX, an already-gone process group counts as cleaned up rather than leaving a stale cleanup token.
• If a workspace was built with GRADLE_USER_HOME=/tmp/... or another isolated Gradle home, pass that path as gradleUserHome so source, mapping, runtime, and project validation lookups use the same Loom cache instead of stale caches under the MCP process home.
• manage-cache reports corrupt Mojang binary-remap cache directories under cacheKinds: ["binary-remap"] with status: "corrupt", and can delete them by selector.artifactId in preview/apply workflows.

Inspect Minecraft source from a version

{
  "tool": "inspect-minecraft",
  "arguments": {
    "task": "class-source",
    "subject": {
      "kind": "class",
      "className": "net.minecraft.server.Main",
      "artifact": {
        "type": "resolve-target",
        "target": {
          "kind": "version",
          "value": "1.21.10"
        }
      }
    }
  }
}

Map or check a symbol

{
  "tool": "analyze-symbol",
  "arguments": {
    "task": "map",
    "subject": {
      "kind": "method",
      "owner": "net.minecraft.server.Main",
      "name": "tickServer"
    },
    "version": "1.21.10",
    "sourceMapping": "mojang",
    "targetMapping": "intermediary",
    "signatureMode": "name-only",
    "detail": "standard"
  }
}

Summarize a mod JAR

{
  "tool": "analyze-mod",
  "arguments": {
    "task": "summary",
    "subject": {
      "kind": "jar",
      "jarPath": "/path/to/mymod-1.0.0.jar"
    }
  }
}

Validate a workspace

{
  "tool": "validate-project",
  "arguments": {
    "task": "project-summary",
    "subject": {
      "kind": "workspace",
      "projectPath": "/workspace/modid",
      "discover": ["mixins", "access-wideners", "access-transformers"]
    },
    "preferProjectVersion": true,
    "preferProjectMapping": true
  }
}

Workspace summaries still default to discovering mixins and access wideners. Add "access-transformers" to subject.discover when you want Access Transformer files included in the summary run.

Documentation

• Detailed example requests for copyable payloads and common workflows
• Tool and configuration reference for exact inputs, outputs, resource behavior, environment variables, and migration notes. Start with the Which Tool for Which Question decision table when you are not sure which tool to call.
• 日本語 README for a Japanese onboarding overview

Tool Surface

Start with these top-level workflow tools unless you already know the exact specialized operation you want. The lower-level tools remain available for narrow follow-up work and automation.

Top-Level Workflow Tools

<!-- BEGIN GENERATED TOOL TABLE: top-level-workflow-tools -->

| Tool | Purpose | | --- | --- | | inspect-minecraft | Inspect versions, artifacts, classes, files, source text, and workspace-aware lookup flows | | analyze-symbol | Handle symbol existence checks, namespace mapping, lifecycle tracing, workspace symbol resolut