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

Tool Parameters

Parameter	Type	Required	Default	Description
mc_version	string	Yes	-	Minecraft version (e.g. "1.12.2", "1.20.1")
expression	string	Yes	-	Boolean search expression
page	number	No	1	Page number (1-indexed)
limit	number	No	20	Results per page (max 100)
output	string	No	default template	Output format template using %variable% syntax

Output template variables: %type%, %obf_class%, %deobf_class%, %obf_name%, %deobf_name%, %srg_name%, %obf_desc%, %deobf_desc%, %access%, %is_static%, %sideonly%, %match%, %mismatch%

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 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 all text columns (excludes sideonly)
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/field descriptors
modifier	access, is_static	Access level and static status (note: access is always empty — data sources lack access info)
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.8.8–1.9.4, 1.10.2–1.11.2	SRG ZIP + MCP Stable CSV + static_methods
Legacy TSRGv1	1.12.2–1.14.4, 1.15–1.15.2	TSRGv1 + MCP Stable CSV + static_methods + constructors
Legacy ProGuard	1.16.1–1.16.5	TSRGv1 + Mojang ProGuard + static_methods
Modern	1.17–1.17.1, 1.18–1.18.2, 1.19–1.19.4, 1.20–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

Format: [type] obf_class/obf_name -> deobf_class deobf_name srg_name obf_desc deobf_desc access is_static sideonly
Found 382 results for "Entity&Player" in MC 1.12.2 (page 1/39)

  1. [method] aed/cD -> net/minecraft/entity/player/EntityPlayer.getAbsorptionAmount func_110139_bj ()F  non-static common
  2. [method] aed/bM -> net/minecraft/entity/player/EntityPlayer.applyEntityAttributes func_110147_ax ()V  non-static common
  ...

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 + mapping-info update
│   └── search/
│       ├── index.ts          # Barrel exports
│       ├── expression.ts     # Boolean expression parser (AND/OR/braces)
│       └── csv-reader.ts     # CSV reader + scoring + in-memory cache
├── 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.