Skip to main content
Glama
re-il2cpp

re-il2cpp

by Heretek-RE

re-il2cpp

An MCP server that reads Unity IL2CPP global-metadata.dat files to recover the original C# class, method, field, and parameter names that the IL2CPP compiler stripped from GameAssembly.dll. Drives Claude Code's reverse engineering on Unity games.

The format is reverse-engineered from the public Il2CppDumper MetadataLoader.cs.

Install

pip install -e ./servers/re-il2cpp[rva]   # [rva] pulls in LIEF for resolve_method_rva

Without the [rva] extra, all 12 tools in the table walker work; only resolve_method_rva requires LIEF. The repo's install.sh calls the [rva] form automatically.

Related MCP server: revula

What it does

IL2CPP compiles a Unity C# project into native x86_64 / ARM64 code. The resulting GameAssembly.dll (often 100s of MB) has all the C# class names mangled away. But the unprotected global-metadata.dat (typically 5-15 MB) sitting next to it still has every original C# symbol name as a plain UTF-8 string. This server reads that file and exposes the class graph as JSON.

What it does NOT do

  • Does not crack encrypted-VM bytecode (any commercial variant) — use re-drm-fingerprint on GameAssembly.dll for that.

  • Does not recover C# source code — only the class/method/field names. The bodies are in GameAssembly.dll, which is the encrypted-VM bytecode-protected IL2CPP runtime.

  • Does not parse Unity asset bundles (level*, sharedassets*). Use re-format-decode for those.

  • Does not fully resolve return_type_index / type_index for methods and fields to a C# type name. The walker returns raw type indices; full name resolution requires reading s_Il2CppMetadataRegistration::types[] from GameAssembly.dll, which is a v2.3.0 follow-up.

Supported versions

Unity 2019.4 - 2022.3 LTS lines (metadata header versions 24, 25, 26, 27, 28, 29). The bundled test target (Unity 2020.3.15f2, header v27) is the canonical integration-test sample.

Tools

Metadata header

  • check_il2cpp(metadata_path) — confirm the file is a real global-metadata.dat, return Unity version, header version, and per-table counts.

String table (fast enumeration)

  • list_strings(metadata_path, substring="", limit=500) — return strings from the string table (the unprotected C# symbol table). Filter by substring.

  • list_namespaces(metadata_path) — return a sorted list of namespaces extracted from class FQNs in the string table.

  • list_classes(metadata_path, namespace="", limit=500) — return class FQNs (filterable by namespace).

  • search_strings(metadata_path, substring, limit=50) — substring search; useful for finding asset-bundle paths, save keys, or specific gameplay terms in the metadata.

Binary tables (structured class graph)

  • get_type_definitions(metadata_path, namespace="", limit=500) — walk the typeDefinitions table; return per-class parent, method/field/property/event counts, type index, and token.

  • get_methods(metadata_path, class_fqn, limit=500) — typed methods of a class with token, parameter count, return type index.

  • get_fields(metadata_path, class_fqn, limit=200) — typed fields of a class with type index.

  • get_parameters(metadata_path, method_fqn, limit=50) — typed parameters of a method in declaration order.

  • get_properties(metadata_path, class_fqn, limit=200) — properties with has_getter / has_setter flags.

  • get_events(metadata_path, class_fqn, limit=200) — events with has_add / has_remove / has_raise flags.

  • get_images(metadata_path) — list of IL2CPP images (assemblies) with type ranges and exported-type counts.

RVA cross-reference (requires pip install re-il2cpp[rva])

  • resolve_method_rva(metadata_path, gameassembly_path, method_fqn) — resolve a Namespace.ClassName.MethodName to its GameAssembly.dll RVA by parsing the runtime registration structures. Pass the returned function_rva to re-rizin.disassemble_function to read the function body. For stripped GameAssembly.dll (the default for shipped Unity games), returns the structured data plus the IL2CPP mangled name to use with re-rizin.search_bytes.

Available Tools

14 tools
check_il2cppB

Read the metadata header and return version + per-table counts.

Args: metadata_path: optional path to global-metadata.dat. If empty, returns the server's status (no path is OK).

Inputs: metadata_path.

get_assembly_typesA

Enumerate every type in one IL2CPP assembly.

Unlike :func:list_classes (which scans the string table and misses root-namespace types), this walks the typeDef range owned by a specific image — use it to enumerate the publisher's actual game code (Assembly-CSharp.dll) or a specific engine module (UnityEngine.CoreModule.dll).

Each record: {fqn, namespace, name, type_index, method_count, field_count, property_count, event_count, nested_type_count, parent_index, token, flags} — same shape as :func:get_type_definitions.

Args: metadata_path: path to global-metadata.dat image_name: assembly file name (e.g. "Assembly-CSharp.dll") limit: maximum results

Inputs: metadata_path (required), image_name (required), limit. Returns: result

get_eventsA

Return the events of a class.

Args: metadata_path: path to global-metadata.dat class_fqn: fully qualified class name limit: maximum events to return (default 200)

Inputs: metadata_path (required), class_fqn (required), limit. Returns: result

get_fieldsC

Return the fields of a class as a structured list.

Args: metadata_path: path to global-metadata.dat class_fqn: fully qualified class name limit: maximum fields to return (default 200)

Inputs: metadata_path (required), class_fqn (required), limit. Returns: result

get_imagesA

Walk the binary images table; return assembly image records.

Each image corresponds to one IL2CPP assembly (e.g. Assembly-CSharp.dll, UnityEngine.CoreModule.dll). The name field is the assembly file name; the type_count is the size of the typeDef range owned by this image.

Args: metadata_path: path to global-metadata.dat

Inputs: metadata_path (required). Returns: result

get_methodsA

Return the methods of a class as a structured list.

Use this instead of search_strings for typed method discovery.

Args: metadata_path: path to global-metadata.dat class_fqn: fully qualified class name (e.g. "MyGame.PlayerController") limit: maximum methods to return (default 500)

Inputs: metadata_path (required), class_fqn (required), limit. Returns: result

get_parametersA

Return the parameters of a method (in declaration order).

Args: metadata_path: path to global-metadata.dat method_fqn: "ClassName.MethodName" (e.g. "MyGame.PlayerController.TakeDamage") limit: maximum parameters to return (default 50)

Inputs: metadata_path (required), method_fqn (required), limit. Returns: result

get_propertiesB

Return the properties of a class.

Args: metadata_path: path to global-metadata.dat class_fqn: fully qualified class name limit: maximum properties to return (default 200)

Inputs: metadata_path (required), class_fqn (required), limit. Returns: result

get_type_definitionsA

Walk the binary typeDefinitions table; return structured records.

Unlike list_classes (which harvests the string table for FQNs), this reads the actual record array and returns parent, type_index, method_count, field_count, etc. for each class.

Args: metadata_path: path to global-metadata.dat namespace: if set, only return typeDefs whose FQN starts with namespace + "." limit: maximum results (default 500)

Inputs: metadata_path (required), namespace, limit. Returns: result

list_classesA

Return class FQNs from the string table.

Args: metadata_path: path to global-metadata.dat namespace: if set, only return classes whose FQN starts with namespace + "." (e.g. "UnityEngine") limit: maximum classes to return (default 500)

Inputs: metadata_path (required), namespace, limit. Returns: result

list_namespacesA

Return a sorted list of namespaces with class counts.

Scans the string table for class FQNs and buckets them by namespace. The class count is an upper bound (a FQN-shaped string might be a non-class entity, though rare).

Args: metadata_path: path to global-metadata.dat limit: maximum namespaces to return (default 200)

Inputs: metadata_path (required), limit. Returns: result

list_stringsA

Return strings from the unprotected C# symbol table.

Args: metadata_path: path to global-metadata.dat substring: if set, only return strings containing this case-sensitive substring limit: maximum number of results to return (default 500)

Inputs: metadata_path (required), substring, limit. Returns: result

resolve_method_rvaA

Resolve a method FQN to its GameAssembly.dll RVA.

Walks the global-metadata.dat typeDef/method tables to find the method, then parses GameAssembly.dll to look for the s_Il2CppCodeRegistrations global. If the binary is non-stripped and contains the registration symbols, the pointer table's RVA is reported. If the binary is stripped (the default for shipped Unity games), the function returns rva_status="binary_stripped" plus the IL2CPP mangled name to use with re-rizin.search_bytes.

Requires pip install lief (an optional dep — install via pip install re-il2cpp[rva]).

Args: metadata_path: path to global-metadata.dat gameassembly_path: path to GameAssembly.dll method_fqn: "Namespace.ClassName.MethodName"

Inputs: metadata_path (required), gameassembly_path (required), method_fqn (required).

search_stringsA

Substring search of the C# symbol table.

Returns [{index, string}] matches. Useful for finding asset paths, save keys, or specific gameplay terms in the metadata.

Args: metadata_path: path to global-metadata.dat substring: case-sensitive substring to search for limit: maximum matches to return (default 50)

Inputs: metadata_path (required), substring (required), limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct aspect of IL2CPP metadata: metadata header, assemblies, type definitions, class members, strings, namespaces, and RVA resolution. Overlaps like get_assembly_types, get_type_definitions, and list_classes are clearly differentiated in their descriptions, leaving no ambiguity.

    Naming Consistency4/5

    The naming pattern is mostly consistent with verb_noun (get_*, list_*, search_*, resolve_*). A minor deviation is 'check_il2cpp' instead of 'get_metadata' but it is a single outlier. Overall patterns are clear and predictable.

    Tool Count5/5

    With 14 tools, the count is well within the ideal 3-15 range. Each tool serves a specific purpose without redundancy or bloat, perfectly scoped for a metadata inspection server.

    Completeness4/5

    The tool set covers the main metadata operations: header info, assembly listing, type definitions, class members, string search, and RVA resolution. A minor gap is lack of a direct 'get_class_by_fqn' tool, but this can be worked around with list_classes and get_type_definitions. Overall, it is fairly complete for read-only analysis.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables LLMs to autonomously reverse engineer applications through Cutter, allowing them to decompile binaries, analyze code, and rename methods programmatically.
      34
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for safely inspecting and editing Unity/VRChat prefabs, scenes, and assets. It diagnoses override collisions, broken references, and runtime exceptions, with read-only YAML analysis and write operations via an Editor Bridge.
      12
      MIT