SevereMCP

Connect Severe to any AI/LLM model of your choice. Run Luau, inspect the game, read memory, and build custom ESPs, aimbots & auto-farms — all from just prompting AI.

License: MIT CI Stars

Star this repo   Get Severe

What is this

SevereMCP is a Model Context Protocol server that hooks Severe's Luau environment up to any AI you use — Claude, ChatGPT, Gemini, or any MCP client. Ask it to run Luau, walk the game tree, list players, read memory, or build an ESP, and it does it live in your session and reads the results back.

How it works

AI client ──stdio (MCP)──> server.py ──ws://127.0.0.1:8790──> bridge.lua  (in Severe's Luau env)

• server.py — the MCP server (stdio, for the AI client) and an embedded WebSocket server, in one process.
• bridge.lua — runs inside Severe and uses Severe's native WebsocketClient to connect out to that server, execute the commands it receives, and send JSON results back.

The split (server = WS server, bridge = WS client) is required because Severe exposes a WebsocketClient but no HTTP request function, so the bridge can't poll an HTTP server.

Setup

Default setup: Severe and the AI client on the same PC. For two machines, see Cross-machine.

1. Install Python deps

pip install -r requirements.txt

2. Add the MCP server to your AI client — pick yours below. Most use this JSON block; replace the path with your real path to server.py:

{
  "mcpServers": {
    "severe-bridge": {
      "command": "python",
      "args": ["C:/path/to/SevereMCP/server.py"],
      "env": { "SEVERE_WS_HOST": "127.0.0.1", "SEVERE_WS_PORT": "8790" }
    }
  }
}

claude mcp add severe-bridge -e SEVERE_WS_HOST=127.0.0.1 -e SEVERE_WS_PORT=8790 -- python C:/path/to/SevereMCP/server.py

[mcp_servers.severe-bridge]
command = "python"
args = ["C:/path/to/SevereMCP/server.py"]
env = { SEVERE_WS_HOST = "127.0.0.1", SEVERE_WS_PORT = "8790" }

Any other MCP-capable client works too — point it at python C:/path/to/SevereMCP/server.py over stdio. The server auto-starts and listens on ws://127.0.0.1:8790 for the bridge.

3. Load the bridge in Severe — run Severe, open its Script tab, and Execute one of:

Easy mode (recommended) — one line, always up to date:

loadstring(game:HttpGet("https://raw.githubusercontent.com/RealSlimShady2000/SevereMCP/main/bridge.lua"))()

Or paste the full contents of bridge.lua. Either way you should see:

[severe-bridge] starting (v1.3.0), candidates: 127.0.0.1
[severe-bridge] connected to ws://127.0.0.1:8790 (v1.3.0)

The bridge auto-reconnects every ~2s, so order doesn't matter. Re-Executing is safe too — a new run kills the previous one instead of stacking a second connection.

4. Confirm — in your AI client, call severe_status → it should report "connected": true.

Tools

Anything without a dedicated tool is reachable via severe_execute — the full Severe API (Drawing/ESP, input, add_model_data, game:HttpGet, crypt, camera, …) is documented via severe_docs.

Examples

• severe_eval → 1+1 ⇒ 2
• severe_execute → print("hi"); return game.Players.LocalPlayer.Name
• severe_inspect → game.Workspace
• severe_search_instances → { "class_name": "Humanoid" }
• severe_memory_read → { "path": "game.Workspace", "offset": 0, "type": "u64" } ⇒ value + rtti
• severe_docs → { "query": "add_model_data" }

Four full demos an agent built live through the MCP — each shows a different technique:

• examples/LoneSurvival_esp.lua — the flagship: a full Player + World ESP with a two-tab SevereLib GUI (Player ESP | World ESP). Player tab: 2D/3D box, skeleton, overlay chams, tracers, health bar, look-direction arrow, name/distance/weapon tags, and a "players behind you" list with live distances. World tab: ore, trees, plants, vehicles, loot crates (labeled by type), dropped loot, dismantlers, landmarks (lighthouse/airfield/…), and airdrop locked crates — each with its own toggle, colour picker and distance slider. All read live via window:getvalue, all clean WorldToScreenPoint (no memory).
• examples/RiotFall_esp.lua — a memory-read ESP + toggle GUI, tested on RIOTFALL: it reverse-engineers real player positions from memory (RIOTFALL hides them behind bone-driven rigs + decoy HumanoidRootParts), draws team-colored boxes + names, and wires toggles into a UI library.
• examples/LoneSurvival_hud.lua — a live status HUD on a DayZ-style survival game: reads Health / Hunger / Thirst / Radiation straight off character attributes (no memory) and paints bars via DrawingImmediate in a RunService.Render loop.
• examples/LoneSurvival_resource_esp.lua — a focused loot / resource / entity ESP via Camera:WorldToScreenPoint (the "clean" non-memory path). Documents two gotchas learned live — skip streamed-out objects (nil position = not loaded) and never call yielding APIs (e.g. send_notification) or blind-chase memory pointers inside the render loop (both froze the game's Luau scheduler during development).

All three wire toggles into the same UI library and are paste-and-run references for "what you can build."

Prompt recipes

Things you can just ask your AI (it explores the game and writes the Luau):

• "Call severe_game_info, then build a box ESP with names for all enemies."
• "Search ReplicatedStorage for remotes, find the one that collects currency, and fire it every 0.5s — stop when my cash stops going up."
• "Walk game.Workspace and list every model that looks like an ore/resource node with its position."
• "Read my character's health from memory and auto-press the heal key when it drops below 50."
• "Reverse-engineer this game's real player positions like the RIOTFALL example and make an ESP."
• "Fire the EquipTool remote, then auto-click every 200ms to farm." (severe_fire_remote + severe_input)

Beyond ESP & aimbot — auto-farms and automation

The real power isn't the ESP — it's that the agent can discover how a game works and write automation for it, live. ESP and aimbot are just the obvious demos; the same read → understand → act loop builds auto-farms, quest bots, collectors, and more for games it has never seen before.

How an agent builds an auto-farm through the MCP:

1. Map the game — severe_tree / severe_search_instances to find currency values, collectibles, NPCs, spawners, quest objects, and the RemoteEvent/RemoteFunctions the game uses.
2. Reverse the actions — severe_execute to read a RemoteEvent's arguments (or decompile/inspect the game's own scripts) and figure out what call collects a coin, sells loot, claims a reward, or hits a mob.
3. Test one action — fire the remote once and read the result (currency went up? item added?) — the agent verifies before looping.
4. Loop it — severe_execute installs a task.spawn / RunService loop that repeats the farm action, teleports between resource nodes (via memory-written CFrame or the game's own teleport remote), and reads a stat to know when to stop (inventory full, quest done).
5. Iterate — if the game patches or behaves oddly, the agent inspects again and adjusts — no waiting for someone to update a static script.

Because every step runs through Luau + memory access, an auto-farm can be as simple as "fire the CollectCoin remote every 0.5s" or as deep as "read the nearest ore node from memory, walk to it, mine it, sell when full." You describe the goal in chat; the agent explores the game and writes the farm — the same way it reverse-engineered RIOTFALL's positions above.

The MCP is a capability layer, not a cheat pack: it gives an AI agent Severe's full Luau + memory reach. What it builds — ESP, aimbot, auto-farm, autoquest, or plain game inspection — is up to your prompt.

Cross-machine (desktop → laptop, optional)

Common setup: the AI client + server.py run on your desktop, and Severe runs on a second PC (a laptop) on the same LAN. The bridge dials out to the server, so the laptop just needs to know the desktop's LAN IP.

   DESKTOP  (server PC, e.g. 192.168.1.50)             LAPTOP  (Severe PC)
 ┌────────────────────────────────────────┐        ┌──────────────────────────────┐
 │  AI client ──stdio──▶ server.py         │        │  Severe.exe                  │
 │                          │              │        │    └─ bridge.lua             │
 │        WebSocket server  ▼              │        │         │                    │
 │        ws://0.0.0.0:8790  ◀─────────────┼───LAN──┼──  WebsocketClient (dials out)│
 └────────────────────────────────────────┘        └──────────────────────────────┘
        binds all interfaces, opens :8790            points at 192.168.1.50:8790 via
        (firewall: allow inbound TCP 8790)           _G.SEVERE_HOST (see below)

1. Desktop (server PC) — start server.py with SEVERE_WS_HOST=0.0.0.0 (bind all interfaces) and allow inbound TCP 8790 through its firewall. You don't need to hunt for its IP — call severe_status and it reports server_lan_ip plus a ready-to-paste cross_machine_hint (or use ipconfig → IPv4 Address, e.g. 192.168.1.50).

2. Laptop (Severe PC) — tell the bridge that IP. Pick whichever matches how you load it:

a) Pasting the full bridge.lua? Put this as the very first line, above everything else, then Execute:

_G.SEVERE_HOST = "192.168.1.50"   -- ⬅ your desktop's LAN IP, NOT this example
--[[ ...the rest of bridge.lua unchanged... ]]

b) Using the one-line loader? Same idea, prepend the override:

_G.SEVERE_HOST = "192.168.1.50"
loadstring(game:HttpGet("https://raw.githubusercontent.com/RealSlimShady2000/SevereMCP/main/bridge.lua"))()

c) Set it once, then forget it — write the host file a single time and afterwards just paste/load the bridge with no prefix:

writefile("severe_host.txt", "192.168.1.50")   -- saved to C:\v2\workspace

You only need to do this once. On its first successful connect the bridge auto-saves the working host to severe_host.txt, so every later plain paste (no _G.SEVERE_HOST line) reconnects to the same PC on its own.

3. Verify from the laptop: Test-NetConnection 192.168.1.50 -Port 8790 → TcpTestSucceeded : True. On Execute you should see:

[severe-bridge] starting (v1.3.0), candidates: 192.168.1.50, 127.0.0.1
[severe-bridge] connected to ws://192.168.1.50:8790 (v1.3.0)

Host resolution order: _G.SEVERE_HOST → severe_host.txt → severe_hosts.txt (optional multi-host list) → 127.0.0.1. The bridge tries each in turn and connects to the first that answers. SEVERE_PORT / SEVERE_TOKEN work the same way (globals or severe_port.txt / severe_token.txt). If you set SEVERE_TOKEN, it must match the server's SEVERE_TOKEN env var.

Severe WebsocketClient quirks (why the bridge is written the way it is)

Hard-won from live testing — don't "simplify" these away:

• WebsocketClient.new(url) blocks until the server sends the first frame. The handshake completing isn't enough — so server.py sends a welcome frame on connect. A silent server makes new() hang 15s → "Scheduler Exhausted".
• Receive is a method, not a signal: s:DataReceived(function(payload, isBinary) end) — not s.DataReceived:Connect(...).
• The DataReceived callback is a C-call boundary — you cannot yield in it. Send and game API calls yield, so the bridge hands each message to task.spawn(...) ("attempt to yield across metamethod/C-call boundary" otherwise).
• Don't use crypt.json in the bridge — crypt.json.decode blocks/yields and trips the watchdog. A bundled pure-Lua JSON is used instead.
• Positions come back as the native vector type (typeof ≠ "Vector3") — read .X/.Y/.Z.
• Players has no GetPlayers() in this build — the bridge falls back to GetChildren() filtered to Player.
• Long scans yield every ~2000 nodes to dodge the 15s watchdog (YIELD_EVERY).

Configuration

Set in the MCP config env block (mirror host/port in bridge.lua if you change them):

Write policy (smart by default). Writes are tiered instead of a blunt on/off switch:

• Property writes (severe_set) are allowed — low risk.
• Memory writes (severe_memory_write) are allowed to an instance path+offset, or to a raw address the session has already read/resolved this session (via memory_read / pointer / read_chain / memory_scan) — a blind write to a never-seen address is refused, since that's what crashes the game. Values are also range-checked against the declared type.
• Set SEVERE_UNSAFE=1 to bypass validation entirely (legacy), or SEVERE_READONLY=1 to block all writes. severe_status reports the active write_policy.

Troubleshooting

• severe_status = connected: false — make sure bridge.lua is Executed in Severe and the host/port match on both sides.
• Tool returns "bridge not connected" — re-run bridge.lua.
• compile error / load error — your Luau source didn't compile; check syntax.
• WebsocketClient is nil — your build may name it differently; adjust the WebsocketClient.new(...) call in bridge.lua.

Files

• server.py — MCP server + WebSocket server + tool definitions
• bridge.lua — in-Severe Luau bridge (WS client, JSON, exec sandbox, dispatch, memory)
• docs/severe-api-full.txt — Severe's own API docs, bundled so severe_docs works offline
• examples/LoneSurvival_esp.lua — full Player + World ESP, two-tab GUI (flagship demo)
• examples/LoneSurvival_hud.lua — attribute-driven survival HUD demo
• examples/LoneSurvival_resource_esp.lua — clean WorldToScreenPoint loot/resource ESP demo
• examples/RiotFall_esp.lua — memory-read ESP + GUI demo
• .mcp.json.example — MCP client config template