Skip to main content
Glama

Forge-Mcp

Python License MCP CI Platform

MCP (Model Context Protocol) server for game modding helpers. Run hex/offset/PE/APK/Unity/Unreal operations from inside Claude Desktop or any MCP client.


๐ŸŽฏ What can it do?

Domain

Key Operations

Hex / Offset

View, search (AOB/wildcard/string), diff saves, value-scan, patch (dry-run), pointer chains, RVAโ†”VAโ†”file-offset, checksum fix (CRC32/Adler/sum)

PE (EXE/DLL)

Sections, imports/exports, entropy, compiler/packer guess, find by name/string-ref, make/verify AOB signatures, cross-build matching, Unicorn emulation, Ghidra headless decompile

APK / Android

apktool unpack/repack+sign, manifest (aapt2 fallback), smali search/patch, native .so exports, Il2Cpp global-metadata dump (parser + Il2CppDumper)

Unity

AssetBundle / .assets list/extract/replace (UnityPy)

Unreal

.pak list/extract/pack (UnrealPak + AES key)

Tables

Schema-driven list/clone/edit/rebuild/validate/references

Archives

zip/tar/7z/unrar unpack & repack (plugin system)

Format Lab

Entropy map, try_decode (zlib/gzip/lzma/xor/base64), guess fields, write .ksy/.hexpat templates, validate

Dynamic

Frida hook script generation, trace diff (two text logs)

Diagnose

Crash log parse, dependency check, mod conflict detection, bisect plan, load-order suggestion

Export

IPS / xdelta patches, Cheat Engine .CT tables, changelog from job log

Undo

Automatic snapshot before every write, single-command rollback


Related MCP server: WolvenKit MCP

๐Ÿš€ Quick Start

1. Install

# From GitHub (recommended)
pip install git+https://github.com/RivaExits0/forge-mcp.git[full]

# Or from source
git clone https://github.com/RivaExits0/forge-mcp.git
cd forge-mcp
pip install -e .[full]          # optional: keystone, UnityPy, kaitaistruct, androguard, lz4

Tool

Purpose

Setup

Ghidra (analyzeHeadless)

Decompile functions

GHIDRA_HOME=/opt/ghidra_12.2

apktool

APK unpack/repack

PATH or APKTOOL_HOME

jadx

Dex decompile

JADX_HOME

Il2CppDumper

Full Il2Cpp dump

PATH

UnrealPak / u4pak

.pak operations

PATH

xdelta3

Binary delta patches

PATH

Frida (frida, frida-trace)

Runtime hooks

pip install frida frida-tools

aapt2

APK manifest (better than zip fallback)

Android SDK build-tools/XX/aapt2

Missing tools produce actionable errors with install links โ€” core functionality never crashes.

3. Configure Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "forge-mcp": {
      "command": "python",
      "args": ["-m", "forge_mcp.server"],
      "cwd": "/absolute/path/to/forge-mcp",
      "env": {
        "FORGE_WORKSPACE_ROOT": "/absolute/path/to/forge-workspaces",
        "GHIDRA_HOME": "/opt/ghidra_12.2"
      }
    }
  }
}

Windows: Use C:\\path\\to\\forge-mcp and C:\\path\\to\\forge-workspaces with double backslashes or forward slashes.

4. Restart Claude Desktop โ†’ You're ready! ๐ŸŽ‰


๐Ÿ›  10 Top-Level Tools

All tools use a module/action pattern with built-in pagination (offset/limit, max 4096) and dry-run support for writes.

Tool

Purpose

Example

open_game

Create/open per-game workspace; import file (exe/apk/save)

{"game_name": "example_game", "source_path": "/games/example_game/example.exe"}

inspect

Read-only queries (pe_info, hex_view, apk_manifest, entropy_mapโ€ฆ)

{"module": "pe", "action": "pe_info", "params": {}}

search

Searches (hex_search, diff_files, value_scan, find_function, guess_fields)

{"module": "hex", "action": "hex_search", "params": {"query": "48 8B ?? ?? ?? 90", "mode": "aob"}}

edit

Write ops with dry_run (hex_patch, smali_patch, table edit, checksum_fix)

{"module": "hex", "action": "hex_patch", "params": {"offset": 0x1234, "bytes_hex": "90 90", "dry_run": false}}

patch_code

Signature/emulation/code-gen (make_signature, verify_signature, emulate_function, frida_script)

{"module": "pe", "action": "make_signature", "params": {"address": 0x140001000, "length": 32}}

rebuild

Rebuild/repack (tables, archives, apk_repack, unreal_pak)

{"module": "tables", "action": "rebuild_offsets", "params": {"schema": {...}}}

validate

Validate artifacts (verify_signature, validate_table, validate_template)

{"module": "pe", "action": "verify_signature", "params": {"signature": "..."}}

export

Distributable artifacts (IPS/xdelta, Cheat Engine .CT, changelog)

{"module": "patch", "action": "export_patch", "params": {"original_path": "...", "modified_path": "...", "out_path": "patch.ips"}}

diagnose

Crash logs, deps, conflicts, bisect, load order, trace diff

{"module": "diagnose", "action": "parse_crash_log", "params": {"path": "crash.dmp"}}

undo

Restore latest (or named) snapshot

{"snapshot_id": "20240615T123456Z_abc123"}


๐Ÿ“– Example Workflow

User: "Open Example Game, find the gold value (I had 100 then 150), and give me a signature that survives updates."

1. open_game({"game_name": "example_game", "source_path": "/games/example_game/example.exe"})

2. search({"module": "hex", "action": "value_scan",
          "params": {"before_path": "save_100.bin", "after_path": "save_150.bin",
                     "value_type": "int32", "limit": 20}})
   โ†’ hits: [{"offset": 0x3A20, "before": 100, "after": 150, "type": "int32"}, ...]

3. inspect({"module": "hex", "action": "hex_view",
            "params": {"path": "work/example.exe", "offset": 0x3A10, "limit": 32}})

4. patch_code({"module": "pe", "action": "make_signature",
               "params": {"path": "work/example.exe", "address": 0x3A20, "length": 32}})
   โ†’ {"signature": "8B 45 ?? 3D 96 00 00 00 75 ?? 48 8B 0D ...", "unique": true}

5. validate({"module": "pe", "action": "verify_signature",
             "params": {"path": "work/example_v1.02.exe", "signature": "..."}})
   โ†’ {"matches": 1, "unique": true}  # survives the patch!

6. export({"module": "patch", "action": "export_patch",
           "params": {"original_path": "original/example.exe", "modified_path": "work/example.exe",
                      "out_path": "gold_patch.ips", "fmt": "ips"}})

๐ŸŽฎ Game Profiles (Adapters)

Drop a folder under profiles/<game>/:

profiles/
  example_game/
    profile.toml        # metadata + config
    schema.ksy          # Kaitai struct for save/table files
    signatures.json     # known AOBs { "gold_offset": "8B 45 ?? ..." }
open_game({"game_name": "example_game", "profile_dir": "profiles/example_game"})

Community adapters are just folders โ€” no code needed.

Example: profiles/example_game/profile.toml

name = "example_game"
version = "1.0"
author = "forge-mcp"
description = "Example game profile template"

๐Ÿ›ก Safety & Ethics

This tool is designed for single-player modding of games you own. The following principles are enforced by design:

  • Only your own copies โ€” Works exclusively with game files you legally own and have local access to.

  • Single-player only โ€” No support for online/multiplayer games, anti-cheat bypass, or DRM removal.

  • Read-only originals โ€” The workspace keeps original files read-only; all edits happen on working copies.

  • Automatic snapshots โ€” Every write operation creates a snapshot first; undo restores byte-for-byte (SHA-256 verified).

  • No binary execution โ€” Static analysis only; Unicorn emulation is fully isolated (no syscalls, no filesystem, no network).

  • Frida on demand โ€” Frida scripts are generated for you to run manually on your own machine; the server never executes them.

  • Path traversal blocked โ€” All paths are resolved inside the workspace root; escape attempts are rejected.


๐Ÿ— Architecture

forge-mcp/
โ”œโ”€โ”€ src/forge_mcp/
โ”‚   โ”œโ”€โ”€ server.py           # FastMCP entry, 10 tools (module/action dispatch)
โ”‚   โ”œโ”€โ”€ core/
โ”‚   โ”‚   โ”œโ”€โ”€ platform_utils.py  # Cross-platform paths, subprocess, file I/O
โ”‚   โ”‚   โ”œโ”€โ”€ workspace.py    # Per-game dirs, read-only originals + work copy
โ”‚   โ”‚   โ”œโ”€โ”€ snapshot.py     # Copy-on-write + undo (SHA-256 verified)
โ”‚   โ”‚   โ”œโ”€โ”€ job_log.py      # JSONL log โ†’ patches + changelog
โ”‚   โ”‚   โ”œโ”€โ”€ paging.py       # offset/limit helper (max 4096)
โ”‚   โ”‚   โ”œโ”€โ”€ profiles.py     # Adapter loader (profile.toml, signatures.json, schema.ksy)
โ”‚   โ”‚   โ””โ”€โ”€ external.py     # Subprocess wrappers (Ghidra, apktool, jadx, Fridaโ€ฆ)
โ”‚   โ””โ”€โ”€ modules/
โ”‚       โ”œโ”€โ”€ hexops.py       # Hex view/search/diff/scan/patch/pointer/offset/calc/checksum
โ”‚       โ”œโ”€โ”€ pe.py           # PE info, signatures, emulate, ghidra decompile, cross-build
โ”‚       โ”œโ”€โ”€ apk.py          # Unpack/repack, manifest, smali, il2cpp, native libs
โ”‚       โ”œโ”€โ”€ unity.py        # UnityPy asset list/extract/replace
โ”‚       โ”œโ”€โ”€ unreal.py       # UnrealPak list/extract/pack (AES)
โ”‚       โ”œโ”€โ”€ tables.py       # Schema-driven CRUD + validate/rebuild/refs
โ”‚       โ”œโ”€โ”€ archives.py     # zip/tar/7z plugin unpack/repack
โ”‚       โ”œโ”€โ”€ formatlab.py    # Entropy, try_decode, guess, write_template, validate_template
โ”‚       โ”œโ”€โ”€ dynamic.py      # Frida script gen, trace diff
โ”‚       โ”œโ”€โ”€ diagnose.py     # Crash, deps, conflicts, bisect, load order
โ”‚       โ””โ”€โ”€ export.py       # IPS/xdelta, Cheat Engine .CT
โ”œโ”€โ”€ profiles/               # Community game adapters
โ””โ”€โ”€ tests/                  # 23 tests (core, hexops, modules, server E2E)
    โ”œโ”€โ”€ fixtures/           # Synthetic PE/APK/table files (no copyrighted content)
    โ””โ”€โ”€ make_fixtures.py    # Regenerates fixtures

๐Ÿงช Development

pip install -e .[full]
pytest -q                    # 23 tests passing
python -m forge_mcp.server   # Stdio server (for MCP clients)

Run Tests

PYTHONPATH=src:tests python -m pytest -v

๐Ÿ“ฆ Release

  • Latest: v0.1.0

  • Install from release: pip install git+https://github.com/RivaExits0/forge-mcp.git@v0.1.0[full]

Create Release (run locally)

git tag -a v0.1.0 -m "forge-mcp v0.1.0: Initial release"
git push origin v0.1.0

๐Ÿ”ง Troubleshooting

Issue

Fix

Ghidra not found

Set GHIDRA_HOME to your Ghidra install (folder containing support/analyzeHeadless)

apktool not found

Install from https://apktool.org/docs/install or set APKTOOL_HOME

aapt2 not found

Install Android SDK build-tools, add to PATH

Frida not found

pip install frida frida-tools

Permission denied on Windows

Run terminal as Administrator or check file permissions

ModuleNotFoundError

Run pip install -e .[full]


๐Ÿ“„ License

MIT โ€” use freely for your own single-player modding. See LICENSE.


๐Ÿค Contributing

  1. Fork the repo

  2. Create a feature branch

  3. Add tests for new functionality

  4. Ensure pytest -q passes

  5. Open a PR


๐ŸŽฌ Demo (Coming Soon)

See docs/demo.md for a recorded demo (GIF/video placeholder).

The demo recording script is at docs/demo-script.md โ€” it walks through the Example Workflow step by step with the exact MCP tool calls.


  • crash-mcp โ€” Deep crash dump analysis (ELF core + Windows minidump). Use diagnose.parse_crash_log for basic parsing; for full stack traces, thread lists, and disassembly, see crash-mcp.

  • emu-mcp โ€” Isolated function emulation with Unicorn. Use pe.emulate_function for simple emulation; for full calling convention support, hooks, and tracing, see emu-mcp.

  • henry-mcp โ€” Static compatibility analysis for EXE/DLL/APK/Kotlin. Use henry_inspect_file and henry_analyze_pair for module compatibility checks.


Available Tools

10 tools
diagnoseB

Diagnosis helpers. Dispatches by module+action.

Modules/actions: diagnose: parse_crash_log (path), check_dependencies (game_dir), find_conflicts (mods), bisect_plan (items), suggest_load_order (mods) dynamic: trace_diff (trace_a, trace_b) external: check_dependencies (tool list)

Inputs: action (required), module (required), params. Returns: result

editA

Edit files/structures. Dispatches by module+action. Supports dry_run.

Modules/actions: hex: hex_patch (path, offset, bytes_hex, dry_run) apk: smali_patch (src_dir, file_rel, old, new, dry_run) tables: clone_entry, edit_fields, rebuild_offsets, checksum_fix format: write_template Every write snapshots first and logs to job_log.

Inputs: action (required), module (required), params. Returns: result

exportB

Export patches/tables. Dispatches by module+action.

Modules/actions: patch: export_patch (original_path, modified_path, out_path, fmt=ips|xdelta) patch: make_trainer_table (addresses, out_path) diagnose: changelog joblog: list

Inputs: action (required), module (required), params. Returns: result

inspectB

Inspect files/structures. Dispatches by module+action.

Modules: pe, apk, unity, unreal, tables, archives, format, hex. Actions: pe: pe_info (path), find_function (path, name|string_ref) apk: apk_manifest (apk_path), native_lib_info (so_path), resource_extract (apk_path, out_dir, pattern) unity: unity_assets (path, action=list|extract) unreal: unreal_pak (pak_path, action=list|extract) tables: list_entries (path, schema) archives: unpack (archive_path, out_dir) format: entropy_map (path, block_size) hex: hex_view (path, offset, limit) Large outputs are paginated via offset/limit inside params.

Inputs: action (required), module (required), params. Returns: result

open_gameA

Open (or create) a per-game workspace.

Use this first before any other tool. Imports source_path into the workspace as a read-only original + working copy. Optionally load a game profile dir.

Args: game_name: Short identifier for the game (e.g. "mygame_v1"). source_path: Path to the game file to import (exe/apk/save). Optional. profile_dir: Path to a profile/adaptor folder. Optional.

Inputs: game_name (required), profile_dir, source_path. Returns: result

patch_codeC

Code patching helpers. Dispatches by module+action.

Modules/actions: pe: make_signature (path, address, length, wildcard_offsets), verify_signature (path, signature), emulate_function (code_hex, entry_offset, arch, args) apk: il2cpp_dump dynamic: frida_script

Inputs: action (required), module (required), params. Returns: result

rebuildA

Rebuild/repack helpers. Dispatches by module+action.

Modules/actions: tables: rebuild_offsets (path, schema), validate (path, schema) archives: repack (src_dir, out_path, format) apk: apk_repack unreal: unreal_pak pack format: validate_template

Inputs: action (required), module (required), params. Returns: result

undoB

Restore the last (or specified) snapshot. Verifies hash after restore.

Inputs: snapshot_id, target_path. Returns: result

validateA

Validate artifacts. Dispatches by module+action.

Modules/actions: pe: verify_signature (path, signature) tables: validate (path, schema) format: validate_template (template_path, sample_files)

Inputs: action (required), module (required), params. Returns: result

Tool Schema Changelog

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

Loading tool schema changelogโ€ฆ

    TDQS

    B3.3/5.0

    Scored across 10 tools

    Disambiguation2/5

    Multiple actions are duplicated across tools: find_function lives in both inspect and search (pe), verify_signature appears in patch_code, validate, and rebuild, rebuild_offsets in both edit and rebuild, and validate in both rebuild and validate. check_dependencies even appears twice within diagnose under different modules. The module dispatch layers are coherent internally, but the cross-tool duplication means an agent can plausibly pick the wrong tool for the same operation.

    Naming Consistency4/5

    All names are snake_case, verb-first, and readable (inspect, search, edit, rebuild, validate, export, diagnose, undo). Minor deviation: open_game and patch_code use verb_noun while the rest are bare verbs, though this actually helps signal they are the entry-point/utility tools.

    Tool Count4/5

    Ten top-level tools is a sensible count for a game-modding forge. However, each tool is a mega-dispatcher bundling 2-9 actions, so the effective surface is much larger than 10 and some tools (inspect, edit) carry heavy action loads.

    Completeness4/5

    The surface covers a full modding lifecycle: open workspace, inspect formats (PE/APK/Unity/Unreal/tables/archives), search/diff, edit with snapshots, patch code, rebuild/repack, validate, export patch tables, diagnose, and undo. Minor gaps: no way to list/close workspaces or manage snapshots directly, and job log access only via export.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      A comprehensive MCP server that provides AI assistants with tools for file system management, Git integration, and shell command execution. It features specialized code utilities for analysis, formatting, and linting to enhance development workflows within Claude Desktop.
      28
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that gives Claude Code access to WolvenKit for Cyberpunk 2077 modding. Extract archives, convert game files to JSON, inspect meshes and textures, manage mods, and build mod projects โ€” all from your terminal.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to research game mods by searching documentation and definitions, inspecting dependencies and playsets, validating saved files with structural and Tiger checks, and preparing or editing mod content with preview and write controls. It also supports starting or previewing the game through a local stdio connection.
      8 npm
      GPL 3.0
    • A
      license
      B
      quality
      C
      maintenance
      Enables an MCP-capable assistant to search and cite Metal Gear Solid V modding documentation, browse catalogued upstream source at pinned commits, and inspect file headers and hashes. It also stages copies of files into isolated job folders to run supported, separately installed archive, texture, language and animation converters, recording commands, logs and changed-file hashes for review.
      25
      GPL 3.0