mcp-serotonin

What is this

Tired of writing ESP blind, guessing whether entity.GetParts works in this mode, or watching the Cheat crash because game.PlaceID is apparently cursed?

This is an MCP server that bridges any MCP-capable LLM agent (Claude Code, Cursor, Cline, Continue…) to the Serotonin Lua runtime. The agent sees the live game - walks the Workspace tree, reads bones and positions, projects world coords to screen, reads memory - then writes Lua tailored to your mode instead of generic templates.

As of v0.3.0 the transport is file-based IPC, so it keeps working with the Serotonin menu closed - no more "open the menu or nothing fires", no more stalls under load.

Why this instead of Studio / debuggers

Roblox Studio     - can't attach to a live public server, only your own place files

Ghidra / x64dbg   - see bytes, not game objects; reverse the whole tree before asking
                    "who's alive?"

CheatEngine       - scans values, can't walk the instance graph or draw overlays

Script executors  - give you Lua, but you write blind and retry on crash

mcp-serotonin gives an LLM agent live access to all of that at once - tree, entity snapshot, bones, screen projection, memory, arbitrary Lua. The agent verifies what's in the mode before coding, tests hypotheses with eval, and ships scripts that work on the first load.

How it works

MCP client  <-- stdio -->  server.py  <-- files -->  bridge.lua  <-->  Serotonin  <-->  Roblox
                                       agent/cmd.json
                                       agent/result.json

server.py writes the next command to C:\Serotonin\files\agent\cmd.json (atomically - temp + replace), bridge.lua reads it on its onUpdate frame, runs it on the game thread, serializes the result (Instances become handles you can pass back; Vector3/Color3 keep their types) and writes agent/result.json. One command at a time, serialized end-to-end - parallel evals stacking inside Serotonin crash the Cheat reliably. No sockets and no async HTTP callbacks: Serotonin only pumps HTTP callbacks while the menu renders, so the old transport stalled with the menu closed; synchronous file IO on onUpdate does not.

Crash protection

Some Lua expressions in Serotonin trigger native C++ exceptions that pcall can't catch - they kill the Cheat DLL. Reading _G, game.DataModel, game.PlaceID, game.LocalPlayer.Backpack, calling Color3:ToHSV() - all confirmed crashers. This release ships with:

• A safe-mode pre-flight in server.py that checks every op against crash_blacklist.json before it leaves the Python process. In safe mode (default: on) blocked ops never reach the Cheat.

• A class-based property allowlist in bridge.lua - only documented properties are read via safe_inspect / dive. Undocumented fields are a known crash vector (Serotonin's proxy tries to resolve them via raw memory and faults on unknown offsets).

• A per-op read/time budget plus a HEAVY_SKIP subtree list, so a tree walk never materialises the whole GetDescendants graph in one native call (the old AV / frame-stall path on big trees).

• A /crash_report endpoint that auto-extracts blacklist rules when you feed it the last-known-bad op. Learn once, never repeat.

Requirements

• Windows 10/11 + Serotonin

• Python 3.10+

• mcp, aiohttp (see requirements.txt)

Install

git clone https://github.com/DeftSolutions-dev/mcp-serotonin.git
cd mcp-serotonin
pip install -r requirements.txt

Drop bridge.lua into your Serotonin scripts folder - usually:

C:\Serotonin\scripts\bridge.lua

(The Scripting tab has an "Open Scripts Folder" button.)

Hook it up to your MCP client

The server speaks stdio, so the config shape is the same for every client. Point it at python C:/path/to/mcp-serotonin/server.py.

Most clients read a JSON file that looks like:

{
  "mcpServers": {
    "serotonin-bridge": {
      "command": "python",
      "args": ["C:/path/to/mcp-serotonin/server.py"],
      "env": { "PYTHONUNBUFFERED": "1" }
    }
  }
}

Put it wherever your client expects it (project-local .mcp.json, user-level config, IDE settings). .mcp.json.example in this repo is the same file, ready to copy.

Run it

1. Launch Roblox + Serotonin.

2. In the Scripting tab, Load bridge.lua. You should see:

   [serotonin-bridge v3] file-IPC loaded - agent/cmd.json <-> agent/result.json (menu-independent)

3. Start your MCP client - it'll spawn server.py over stdio on demand.

4. Call serotonin_ping. If you get "pong", you're done. The Serotonin menu can stay closed - the bridge runs off onUpdate, not the menu render loop.

If it times out, the bridge isn't loaded. Reload the Lua script and check the Cheat console for errors.

Tools (31 wrappers)

Instance / world exploration

Entity / parts / players

Screen / projection

Memory

File sandbox (C:\Serotonin\files)

Audio (safe subset)

audio.PlaySound is intentionally not wrapped because non-WAV input crashes the Cheat with a native SEH exception. Drive PlaySound through serotonin_eval only when you control the bytes (e.g. file.read of a known-good .wav).

UI (drive the Cheat menu)

HTTP endpoints (for shell / debugging)

The file channel is the transport. On top of the MCP tools, server.py still runs a small HTTP server so you can drive the bridge directly with curl (it shares the same file IPC underneath):

Set SEROTONIN_HTTP_ONLY=1 to start only the HTTP server (skip stdio MCP) for shell debugging.

Things that bite (and how this release handles them)

The menu used to gate the transport. Serotonin only pumps http.Get / http.Post completion callbacks while the menu renders, so the old HTTP bridge silently stalled with the menu closed (commands queued, nothing came back). v0.3.0 moves the transport to plain files read/written synchronously on onUpdate, so it no longer depends on the menu at all.

Memory types. The verified accepted types are: byte, short, ushort, int, uint, int64, uint64, float, double, bool, string, ptr, pointer. Tested working against memory.GetBase(). The old int8/16/32 shortcuts are not accepted.

_G is a native crasher. Not just nil - even type(_G) inside pcall takes down the DLL. Blacklisted as regex \b_G\b. Use getfenv(1) if you need the env table.

game.GetService uses dot syntax, not colon. game.GetService("Players") works; game:GetService(...) errors. The Lua game is a sandbox proxy table, not an Instance userdata - it also has no GetChildren, so tree walks scan via GetService(...).

Entity API returns userdata, not indices. Docs say entity.GetPlayers() returns integers; it returns userdata objects. Access fields as p.Name, p.Health; call bone methods as p:GetBonePosition("HumanoidRootPart").

entity.Position is often stale. In FFA / Tank-style modes the cached position stays at (0,0,0). Use p:GetBonePosition("HumanoidRootPart") for the live value. serotonin_players_full does this for you.

Documented-but-broken. Vector3:FuzzyEq doesn't exist (Lua error). Color3:ToHSV() crashes (native). game.GetFFlag / game.SetFFlag crash. game.LocalPlayer.Backpack and ~27 other undocumented LocalPlayer.* fields crash. All blacklisted.

audio.PlaySound crashes on any non-WAV string, cheat.LoadString raises "C++ exception" on every call - both blacklisted. Use loadstring / load instead of cheat.LoadString.

Don't parallelize eval. Two simultaneous evals crash Serotonin. The server holds a semaphore and the bridge keeps a single command slot, so calls are serial end-to-end; stay on the tools and you're safe.

Configuration

Env vars:

• SEROTONIN_HTTP_HOST (default 127.0.0.1)

• SEROTONIN_HTTP_PORT (default 8765)

• SEROTONIN_HTTP_ONLY=1 - start only the HTTP server, skip stdio MCP. Useful for curl debugging.

IPC files (created automatically under the Serotonin sandbox):

• C:\Serotonin\files\agent\cmd.json - server -> bridge (one command, written atomically)

• C:\Serotonin\files\agent\result.json - bridge -> server (one result)

Tunables in bridge.lua (top of file, CFG table):

• op_budget_max - max native property reads per op before a walk aborts with partial data (default 15000)

• op_time_max_ms - soft per-op deadline (default 8000)

• max_depth - default serialization depth (default 3)

• debug - print per-command lines to the Cheat console

Credits

Crash diagnosis and the file-based IPC approach: mixercodes. His mcp-serotonin-v2 found the holes and pinned the real root cause - the menu-closed / async HTTP-callback stall - and the file-based transport this v0.3.0 release ships is his approach. The crash fixes here are effectively his findings and implementation ported back into this bridge. Thanks for the help. 🙏

License

MIT.