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.

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.