WolvenKit

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.

Works offline (no game running needed). Pairs with CET MCP for a complete AI-assisted modding pipeline.

How it works

Claude Code → stdio/JSON-RPC → MCP Server → WolvenKit CLI (cp77tools) → filesystem

Requirements

• Node.js >= 18
• WolvenKit CLI (installed via dotnet):

  dotnet tool install -g WolvenKit.CLI
  

• Cyberpunk 2077 (for game archives)

Setup

# 1. Clone and build
git clone https://github.com/Y4rd13/wolvenkit-mcp.git
cd wolvenkit-mcp
npm install
npm run build

# 2. Add to Claude Code globally
claude mcp add wolvenkit -s user \
  -e "WOLVENKIT_CLI=cp77tools" \
  -e "CP77_GAME_DIR=/path/to/Cyberpunk 2077" \
  -e "CP77_MOD_DIR=/path/to/Cyberpunk 2077/archive/pc/mod" \
  -- node /path/to/wolvenkit-mcp/build/index.js

Tools (45)

Archive Operations

Tool	Description
unbundle_archive	Extract files from .archive with wildcard filter
pack_archive	Pack folder into .archive
archive_info	List all files inside an archive
list_archives	List all game archives
search_archives	Search files across ALL game archives by pattern
list_installed_mods	List installed mod archives with sizes
mod_conflicts	Detect file conflicts between installed mods

File Conversion

Tool	Description
convert_to_json	REDengine file → editable JSON
convert_from_json	JSON → REDengine file
inspect_file	Quick structural summary of a game file
get_game_file	One-step: find in archives → extract → convert to JSON
batch_convert	Convert multiple files to JSON at once
patch_json	Modify specific fields in a game file JSON

Asset Inspection

Tool	Description
get_file_dependencies	List all files referenced by a game file
extract_mesh_info	Mesh details: submeshes, materials, bones
get_texture_info	Texture details: resolution, format, mipmaps
list_entity_components	List entity components and appearances
find_appearances	Search for .app files by pattern
find_materials	List all materials used by a mesh
list_inkatlas_slots	List UI texture atlas slots
get_animation_list	List animations in .anims/.rig files
search_game_files	Search by extension + pattern within an archive

Asset Export/Import

Tool	Description
export_file	Export to raw format (mesh→GLB, texture→PNG)
import_file	Import raw file back to REDengine format
uncook_archive	Extract + export in one step

Mod Projects

Tool	Description
create_mod_project	Scaffold a mod project structure
build_mod	Pack and optionally install mod to game
list_project_files	List files in a mod project
copy_to_project	Extract a game file directly into a mod project
validate_mod	Check project structure and report issues
strip_unused	Find unreferenced/orphaned files in a project
get_cooked_size	Estimate final mod size by file type
generate_tweakxml	Generate TweakXL YAML templates

Mod Management

Tool	Description
backup_archive	Create .bak backup of an archive
restore_archive	Restore archive from .bak backup
compare_archives	Compare mod archive vs original (added/removed files)
merge_archives	Merge multiple archive sources into one
install_mod_from_url	Download and install mod from direct URL

Info & Analysis

Tool	Description
wolvenkit_status	CLI version, paths, availability check
hash_value	Compute FNV1a64 hash for game paths
find_by_hash	Search for a file by its hash value
diff_files	Compare two REDengine files showing changes
analyze_performance	Estimate mod performance impact (mesh/texture sizes)
decompile_script	Search for script files (.reds, .ws) in archives
generate_xlmap	Generate ArchiveXL resource mapping template

Configuration

Variable	Default	Description
WOLVENKIT_CLI	cp77tools	WolvenKit CLI command
CP77_GAME_DIR	(see .mcp.json)	Game installation path
CP77_MOD_DIR	<game>/archive/pc/mod	Mod installation directory

WSL2 Notes

The MCP server runs on WSL2 but calls the Windows WolvenKit CLI via cmd.exe. Paths are automatically converted between WSL (/mnt/g/...) and Windows (G:\...) formats.

License

MIT