forge-mcp
Provides APK/Android modding operations, including apktool unpack/repack and signing, manifest inspection, smali search/patch, native .so export inspection, and Il2Cpp global-metadata dumping.
Provides Unity asset operations for AssetBundle and .assets files, including listing, extracting, and replacing assets via UnityPy.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@forge-mcp search example.exe for the AOB 48 8B ?? ?? 90 and list the matches"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Forge-Mcp
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 |
Unity | AssetBundle / |
Unreal |
|
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 |
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 |
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, lz42. External Tools (Optional but Recommended)
Tool | Purpose | Setup |
Ghidra ( | Decompile functions |
|
apktool | APK unpack/repack | PATH or |
jadx | Dex decompile |
|
Il2CppDumper | Full Il2Cpp dump | PATH |
UnrealPak / u4pak |
| PATH |
xdelta3 | Binary delta patches | PATH |
Frida ( | Runtime hooks |
|
aapt2 | APK manifest (better than zip fallback) | Android SDK |
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-mcpandC:\\path\\to\\forge-workspaceswith 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 |
| Create/open per-game workspace; import file (exe/apk/save) |
|
| Read-only queries (pe_info, hex_view, apk_manifest, entropy_mapโฆ) |
|
| Searches (hex_search, diff_files, value_scan, find_function, guess_fields) |
|
| Write ops with |
|
| Signature/emulation/code-gen (make_signature, verify_signature, emulate_function, frida_script) |
|
| Rebuild/repack (tables, archives, apk_repack, unreal_pak) |
|
| Validate artifacts (verify_signature, validate_table, validate_template) |
|
| Distributable artifacts (IPS/xdelta, Cheat Engine .CT, changelog) |
|
| Crash logs, deps, conflicts, bisect, load order, trace diff |
|
| Restore latest (or named) snapshot |
|
๐ 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;
undorestores 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 |
| Set |
| Install from https://apktool.org/docs/install or set |
| Install Android SDK build-tools, add to PATH |
|
|
| Run terminal as Administrator or check file permissions |
| Run |
๐ License
MIT โ use freely for your own single-player modding. See LICENSE.
๐ค Contributing
Fork the repo
Create a feature branch
Add tests for new functionality
Ensure
pytest -qpassesOpen 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.
๐ Related Projects
crash-mcp โ Deep crash dump analysis (ELF core + Windows minidump). Use
diagnose.parse_crash_logfor basic parsing; for full stack traces, thread lists, and disassembly, see crash-mcp.emu-mcp โ Isolated function emulation with Unicorn. Use
pe.emulate_functionfor 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_fileandhenry_analyze_pairfor module compatibility checks.
๐ Links
Repository: https://github.com/RivaExits0/forge-mcp
MCP Spec: https://modelcontextprotocol.io/
apktool: https://apktool.org/
UnityPy: https://github.com/K0lb3/UnityPy
Available Tools
10 toolsdiagnoseB
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
searchB
Search in files. Dispatches by module+action.
Modules/actions: hex: hex_search (path, query, mode, offset, limit), diff_files (path_a, path_b), value_scan (before_path, after_path, value_type) pe: find_function (path, name|string_ref) apk: smali_search (src_dir, query, limit) format: guess_fields (path, max_fields)
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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseCqualityDmaintenanceA 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.287MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmGPL 3.0
- AlicenseBqualityCmaintenanceEnables 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.25GPL 3.0