English | 中文

Native MC Mapping MCP Server

An MCP (Model Context Protocol) server that provides Minecraft obfuscated name mapping lookups. Helps AI coding agents work with Minecraft's obfuscated Java internals — for modding, plugin development, Mixin, Access Transformers, reflection-based scripting, and more.

What It Does

Minecraft's Java code is obfuscated at runtime — class, method, and field names are replaced with short meaningless identifiers (aed, func_70091_d, m_91087_). This MCP server lets your AI agent:

• Search obfuscated ↔ deobfuscated mappings across 38 Minecraft versions (1.7.10 – 1.20.1)
• Auto-build mapping caches on first use — downloads from NeoForge Maven and Mojang servers
• Boolean expression search — Entity&Player, {Block|Item}&client, func_149645

Use Cases

Scenario	How This Helps
Forge / NeoForge modding	Look up obfuscated method/field names when writing mixins or AT configs
Fabric modding	Find intermediary ↔ named mappings for access wideners
Spigot / Paper plugins	Resolve NMS (net.minecraft.server) class names across versions
Mixin / Access Transformers	Discover the exact obfuscated name to target
Reflection-based code	Find field/method names for getDeclaredField, getMethod, etc.
Scripting engines	Resolve native Minecraft API names (CustomNPCs, CraftTweaker, etc.)
Porting mods	Compare mappings between MC versions to find renamed APIs

MCP Tools

Tool	Description
search	Search Minecraft obfuscated class/method/field name mappings

Quick Install (MCP Client)

Prerequisites

• Node.js ≥ 18

Step 1: Clone & Build

git clone https://github.com/SaltfishSheep/AI-MCP-NativeMinecraftAccess.git
cd AI-MCP-NativeMinecraftAccess
npm install
npm run build

Step 2: Add to Your MCP Client

Add the following to your MCP client configuration:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "native-mc-access": {
      "command": "node",
      "args": ["/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"]
    }
  }
}

OpenCode (opencode.json):

{
  "mcp": {
    "native-mc-access": {
      "type": "local",
      "command": ["node", "/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"],
      "enabled": true
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "native-mc-access": {
      "command": "node",
      "args": ["/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"]
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "native-mc-access": {
      "command": "node",
      "args": ["/absolute/path/to/AI-MCP-NativeMinecraftAccess/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/ with the actual path where you cloned the repo.

Usage

Once configured, your AI agent can call the search tool:

search(mc_version="1.12.2", expression="Entity&Player")

Example queries:

Query	Description
Entity&Player	Entries containing both "Entity" AND "Player"
Entity::classname	Class name exactly "Entity"
walk:method	Methods with "walk" in name
static::modifier	is_static or access exactly "static"
Potion:classname&Duration:name	Class name "Potion", name "Duration"
{Block|Item}&client	Client-side Block or Item entries
func_70091_d	Find a specific SRG method name by ID
KeyBinding	All entries mentioning KeyBinding
output="%deobf_class%"	Deduplicated class list

Expression syntax:

Syntax	Meaning	Example
term	Case-insensitive substring match (exact case scores higher)	KeyBinding
term:modifier	Restrict search to specific columns	Potion:classname, walk:method
term::modifier	Strong modifier — exact match required	Entity::classname
net.minecraft.Entity	Dot notation — matches net/minecraft/Entity and net/minecraft$Entity	net.minecraft.entity.Entity
&	AND (both must match, higher precedence)	Entity&Living
|	OR (either must match)	Entity|Player
{}	Grouping	{a|b}&c

Modifiers:

Modifier	Searches	Description
all	all columns	Default — searches everything
class	obf_class, deobf_class	Full class path (e.g. net/minecraft/entity/Entity)
classname	deobf_class (after last /)	Class name only (e.g. Entity from net/minecraft/entity/Entity)
package	deobf_class (before last /)	Package only (e.g. net/minecraft/entity)
name	obf_name, deobf_name, srg_name	Field/method names (methods+fields only)
method	obf_name, deobf_name, srg_name	Method names only (filters type=method)
field	obf_name, deobf_name, srg_name	Field names only (filters type=field)
desc	obf_desc, deobf_desc	Method descriptors
modifier	access, is_static	Access level and static status
side	sideonly	Side filter (common/server/client)

Tips: Use Player&Entity instead of PlayerEntity for cross-version compatibility, as naming conventions differ across MC versions.

Supported Versions

38 Minecraft versions across 4 workflow types:

Workflow	Versions	Data Sources
Legacy SRG	1.7.10, 1.8–1.11.2	SRG ZIP + MCP Stable CSV
Legacy TSRGv1	1.12.2–1.15.2	TSRGv1 + MCP Stable CSV + static_methods + constructors
Legacy ProGuard	1.16.1–1.16.5	TSRGv1 + Mojang ProGuard
Modern	1.17–1.20.1	TSRGv2 + Mojang ProGuard

How It Works

1. On first search for a given MC version, the server downloads mapping data from NeoForge Maven and Mojang
2. It parses SRG/TSRG/ProGuard formats and merges them with MCP CSV data
3. The merged cache is stored as .mapping-caches/<version>.csv
4. Subsequent searches use the cached data (validated against package.json version)
5. Boolean expressions are parsed into an AST and evaluated against all CSV rows

Output Format

Found 382 results for "Entity&Player" in MC 1.12.2 (page 1/39)

  1. [method] aed.cD -> net/minecraft/entity/player/EntityPlayer.getAbsorptionAmount  srg=func_110139_bj  desc=()F  sideonly=common  match=2.0 mismatch=42
  2. [method] aed.bM -> net/minecraft/entity/player/EntityPlayer.applyEntityAttributes  srg=func_110147_ax  desc=()V  sideonly=common  match=2.0 mismatch=42
  ...

Project Structure

AI-MCP-NativeMinecraftAccess/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── util.ts               # Shared utilities (CSV parsing, package version)
│   ├── version-table.ts      # URL mapping table for 38 MC versions
│   ├── builder/
│   │   ├── index.ts          # buildMappingCache entry point
│   │   ├── download.ts       # HTTP fetch + minimal ZIP reader
│   │   ├── parsers.ts        # SRG, TSRGv1, TSRGv2, ProGuard, CSV parsers
│   │   ├── workflows.ts      # 4 merge workflow builders
│   │   └── cache.ts          # CSV cache writer + validator
│   └── search/
│       ├── index.ts          # Re-exports
│       ├── expression.ts     # Boolean expression parser (AND/OR/braces)
│       └── csv-reader.ts     # CSV reader + paginated search
├── dist/                     # Built JavaScript (entry: dist/index.js)
└── .mapping-caches/          # Generated cache files (gitignored)

License

MIT License — see LICENSE.

Third-Party Data

• Mojang mappings — Provided under Mojang's custom license. This server fetches them at runtime; it does NOT redistribute them.
• MCP mappings — Maintained by the Mod Coder Pack community, distributed via NeoForge Maven.