Skip to main content

deadlock-mcp logo

DeadlockMCP

An MCP server for building Deadlock UI mods.

Live-edit Deadlock's Panorama UI (XML/CSS/JS) while the game runs.

Connect it to an MCP client with an agent and ask for things like "find the panel that shows my stat boosts and move it to bottom-center".

The server installs an addon that uses the dev tools to update the UI. The agent inspects the live panel tree, tries CSS and JS in the running game, takes screenshots to check the result, and then compiles the change into a mod VPK.

⚠️ Status: Alpha. Tested only on Bazzite (KDE Wayland) with Proton, Deadlock build #6,861 (Nov 2026). Other Linux setups may work but are untested. Windows and macOS aren't supported yet; help supporting other platforms is welcome.

Getting started

You need Linux with Deadlock installed through Steam (running under Proton) and uv. Steam must be running when the game launches, so the game can log in.

  1. Add the server to your MCP client (stdio). It must run on the same Linux desktop session as the game:
    {
      "mcpServers": {
        "deadlock": {
          "command": "uvx",
          "args": ["deadlock-mcp"]
        }
      }
    }
    
    With Claude Code: claude mcp add deadlock -- uvx deadlock-mcp. Paths are auto-detected; TECH.md lists the environment variables to override them.
  2. Ask your agent to set it up. It runs setup, which downloads Source 2 Viewer CLI and CSDK 13 (about 1.6 GB) and creates a Wine prefix for the compiler. If the CSDK download fails, it asks you to download the .7z into ~/Downloads yourself. setup also lists any missing system tools (7z, xdotool, ImageMagick, umu-run) with the install command for your distro.
  3. Ask it to start the game: it runs bridge_install, then launch_game(map="new_player_basics"). The game boots straight into a sandbox match with the full HUD, ready for changes.

Making a mod

  1. Get set up as described above, with the game running in the sandbox.
  2. Tell your agent what you want, for example "move my stat boosts to bottom-center" or "make the ability cooldown numbers bigger". It finds the panels, tries the change live, and takes screenshots to check. Keep giving feedback until it looks right.
  3. Ask it to package the mod, for example "make that permanent and install it as a mod called my_hud". You get ~/.local/share/deadlock-mcp/mods/my_hud/pak01_dir.vpk, and with install it's also copied into game/citadel/addons/ under the next free pakNN_dir.vpk name.

The exported VPK is a normal mod: it doesn't include the bridge and doesn't need this tool to run.

Tools

Most tools take ui='hud' | 'dashboard' | 'overlay' to pick a panel tree; the default auto uses the first one that's ready.

Game

tool description
status Reports paths, game and bridge state, and anything that needs fixing, and pings each in-game bridge.
launch_game Launches Deadlock with the dev addon mounted, optionally straight into the sandbox map with the full HUD.
quit_game Closes Deadlock.
console_log Returns recent game console output, optionally regex-filtered.
screenshot Captures the game window (or the whole screen) as an image, with an optional crop.

Game files

tool description
ui_files Lists the Panorama files shipped in the game, with a regex filter.
ui_source Decompiles a shipped Panorama layout, stylesheet or script to source.

Live editing

tool description
panel_tree Dumps the live panel hierarchy (id, type, layout, size, position, text) under a panel.
panel_find Finds live panels with a CSS-like selector.
js_eval Runs JavaScript in the game's UI and returns the result.
css_apply Applies CSS to live panels as inline styles, re-applying it as panels are recreated.
css_clear Removes one live CSS sheet, or all of them.
xml_load Compiles Panorama XML (and optional CSS) and loads it into the live UI.
layout_live_edit Live-edits an existing game layout's stylesheet, applying only the changed declarations.
layout_live_revert Reloads the original layout into panels changed by layout_live_edit.
panel_delete Deletes a live panel by id.

Building and exporting

tool description
compile_source Compiles a Panorama file into the dev addon as a permanent override (applies after a restart).
list_overrides Lists the compiled files in the dev addon.
remove_override Removes a compiled override from the dev addon.
export_mod Exports the overrides, without the bridge, as a standalone mod VPK, and optionally installs it into the game.

Setup

tool description
setup Installs Source 2 Viewer CLI, CSDK 13 and the compiler's Wine prefix, and lists missing system tools.
bridge_install Builds the in-game bridges and packs them into the dev addon; re-run after a game update.
bridge_uninstall Removes the bridge files from the dev addon.
addons_mount Adds or removes the dev addon's search path in gameinfo.gi.

Parameters and implementation details: TECH.md.

What it installs

setup puts everything under ~/.local/share/deadlock-mcp/ ($DEADLOCK_MCP_DATA to move it):

  • tools/s2v/: Source 2 Viewer CLI, to decompile game files.
  • tools/Reduced_CSDK_13/: CSDK 13, whose resourcecompiler.exe compiles Panorama files (about 5.4 GB).
  • wine/: a Wine prefix made by Proton, to run the compiler.
  • mods/: exported mods.

It doesn't install system packages.

What it modifies

  • game/citadel/gameinfo.gi: launch_game adds a marked block that mounts the dev addon (and citadel/addons, so installed mods still load), saving the previous file as gameinfo.gi.mcp-bak. The addon is unmounted automatically when that game exits; if the game crashed or the PC rebooted, status warns and addons_mount(False) removes it.
  • game/citadel/mcp_addons/: the dev addon, holding the bridge, your compiled overrides, and the request files the server talks to the game through.
  • game/citadel/console.log: the game writes it (-condebug) and the server deletes it on each launch.
  • game/citadel/addons/: export_mod(install=True) copies the mod there.
  • ~/.local/share/deadlock-mcp/tools/Reduced_CSDK_13/{content,game}/citadel_addons/mcp_bridge/: sources and compiler output.
  • ~/.cache/deadlock-mcp/: decompiled sources, launch and watcher logs.

No shipped game files are changed. Agent-launched games are for building mods: play your matches from a normal Steam launch, which doesn't load the bridge.

License

MIT. Deadlock and its assets belong to Valve.

Metadata

Release files for deadlock-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for deadlock-mcp 0.1.0
File Size Uploaded Provenance Actions
deadlock_mcp-0.1.0.tar.gz 88.6 kB With provenance Details for deadlock_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for deadlock-mcp 0.1.0
File Interpreter ABI Platform Actions
deadlock_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for deadlock_mcp-0.1.0-py3-none-any.whl

Total release size: 154.2 kB

Release files / deadlock_mcp-0.1.0.tar.gz

Download URL deadlock_mcp-0.1.0.tar.gz
Size 88.6 kB
Tags Source
SHA-256 checksum
How to use checksums
39f9dd7e13afa6b2f56ca6596d6d5203c06134066747a4038b0869d91f3b6a30
BLAKE2b-256 checksum
How to use checksums
9f004a1b6ce724b755b6578831628c26c0475a501272a7cc43e658c5fe2cc1f9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / deadlock_mcp-0.1.0-py3-none-any.whl

Download URL deadlock_mcp-0.1.0-py3-none-any.whl
Size 65.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bc0ec032bc255637667e0883eb407e063eb70a186a081051e1b1f685524466e5
BLAKE2b-256 checksum
How to use checksums
ddf795e342fbaa368ab61016a9bdaf1836f8459bb40774b8762818f443a6eac4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for deadlock-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for deadlock_mcp-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page