owmcp
Drive the Opiumware Roblox executor on macOS via MCP: run Luau, inspect logs, scripts, network traffic, screenshots, and instance status.
Check live Roblox instances, game/player, kicked status, and decompiler state.
Execute Luau code or files with return values, prints, errors, tracebacks, timeouts, and port selection.
Read console logs filtered by level, regex, time, since last execute, or new entries.
List, search, and read decompiled client-side scripts, cached as .luau files.
Capture remote traffic: FireServer/InvokeServer and OnClientEvent with args, returns, and calling scripts.
Screenshot the Roblox window even when covered, for visual verification.
Drives the Opiumware Roblox executor attached to a live Roblox client, letting an agent run Luau code or script files, read console logs, browse and grep decompiled client scripts, capture and inspect remote network traffic (FireServer, InvokeServer, OnClientEvent), and take screenshots of the Roblox window to iteratively test and verify scripts in-game.
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., "@owmcp run print(game.Players.LocalPlayer.Name) and show me the output"
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.
owmcp
An MCP server that lets AI agents drive the Opiumware Roblox executor on macOS. Agents can write a script, run it, check the console or a screenshot, and iterate on their own. It's vibeslopped (mostly written with AI tools), so expect some rough edges, and feel free to open an issue.
Tools
Tool | What it does |
| Shows live Roblox instances, their game and player, whether they were kicked, and the decompiler state. |
| Runs Luau code or a file and returns values, prints, and errors with tracebacks. Runs that time out are cancelled. |
| Reads the Roblox console, filtered by level, regex, time, or since the last |
| Lists, searches, and reads decompiled client scripts, mirrored to |
| Captures remote traffic with arguments, return values, and calling scripts. Hooks exist only while capturing. |
| Captures the Roblox window, even when covered, to check ESP, UI, and menus. |
| Returns to the last game after a kick or from the home screen, in the same server or any other. |
When the client is kicked, results carry a warning so the agent knows to rejoin. Large outputs are saved to $TMPDIR/owmcp/, and tools return a path and a preview instead.
Related MCP server: Roblox Executor MCP Server
Setup
You need macOS, Node.js 18+, and Opiumware attached to Roblox. screenshot also needs Screen Recording permission for your MCP client.
git clone https://github.com/bzzimmy/owmcp && cd owmcp
npm installAdd the server to your MCP client, such as Claude Desktop or ~/.config/mcp/mcp.json:
{
"mcpServers": {
"opiumware": {
"command": "node",
"args": ["/absolute/path/to/owmcp/build/index.js"]
}
}
}Keep the server running between calls so the decompile cache survives, and allow tool calls up to about 5 minutes. Then join a game and call status to check the connection.
How it works
Scripts go to Opiumware's local TCP server on ports 8390–8399, wrapped in lua/runtime.luau, which captures their output and posts it back over a local HTTP callback. Logs and kick detection come straight from ~/Library/Logs/Roblox, and decompiling uses Opiumware's bundled decompiler, started on demand.
Development
npm run build # compile TypeScript
npm run lint # ESLint, tsc, and luau-lspRebuild after pulling, since clients run build/index.js.
Disclaimer
Executors violate the Roblox Terms of Use and can get your account banned. execute runs arbitrary code in your client, so only connect agents you trust.
License
MIT © 2026 Ben Zimmermann
Available Tools
6 toolsexecuteExecute LuauA
Run Luau in the Roblox client (Opiumware, thread identity 8) and get back return values, print/warn output, and errors with traceback.
Just
returnvalues; tables, Instances, Vector3s etc. are serialized automatically. Don't JSONEncode.Each run has its own global scope. Use getgenv() to keep state between runs. _G is the executor's; the game's is getrenv()._G.
Full executor API is available (getgc, hookmetamethod, decompile, firesignal, ...). To run a local file use the file parameter; the executor's own readfile/loadfile only see Opiumware's workspace folder.
Heavy scans (getgc, GetDescendants on large trees) must yield (task.wait() every few thousand items) or they freeze the game.
Long-running code (loops, listeners) should task.spawn and return right away. On timeout the run itself is cancelled, but threads it spawned keep running.
Errors returned here are NOT in the console. Errors/prints after the run returns (spawned/deferred code) only show in logs: use logs sinceExecute=true.
Separate execute calls made in parallel may run in any order.
Large results are saved to a temp file whose path is returned.
Inputs: code, file, port, timeout.
logsRead console logsA
Read the Roblox client console (print/warn/error from all scripts, including the game's own), newest last.
Debug loop: after
execute, call with sinceExecute=true to see everything logged since that run started (deferred errors, spawned loops), or new=true for everything since the previous logs call.Errors from code run via execute are tagged "mcp:"; from the Opiumware editor "Opiumware:". Filter with grep.
Repeated consecutive lines are collapsed to (xN). Long messages are truncated; when anything is cut, the full results are saved to a temp file you can grep.
Inputs: new, grep, level, limit, +2 more.
networkCapture remote trafficA
Capture remote traffic between the client and server: outgoing FireServer/InvokeServer (with InvokeServer return values and the calling script) and incoming OnClientEvent.
start: begin a fresh capture (replaces the previous log). stop: stop recording and remove the hooks (the log is kept). read: view the log (works while running).
Hooks only exist while capturing, so stop as soon as you have what you need.
read without
remotegives a per-remote summary (count, rate, latest args); withremoteit lists individual calls with arguments, collapsing consecutive identical calls.Calls made by your own executed code are marked [by executor].
Long results are truncated and the full log is saved to a temp file.
Inputs: action (required), port, limit, remote, +1 more.
screenshotScreenshotA
Capture the Roblox window as the player sees it (works even if other windows cover it). Use to verify visual scripts (ESP, UI, menus). Each image costs ~1K tokens, so use sparingly.
Inputs: port.
scriptsGame scriptsA
Read the game's client-side code (LocalScripts, ModuleScripts; server Scripts never reach the client). Decompiled sources are cached and saved as .luau files in a temp folder mirroring the game tree, so you can also grep/read them directly.
list: script paths (optionally filtered).
search: regex across all decompiled sources, returns path:line matches. The first search decompiles everything (a few seconds).
read: one script's source with line numbers, 150 lines at a time (use startLine/endLine).
Inputs: action (required), path, port, limit, +4 more.
statusStatusA
Check the connection: which Roblox instances (Opiumware ports) are live, what game/player each is in, and whether the decompiler is running. Call this first or when something isn't working.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a clearly distinct domain: screenshot (visual capture), status (connectivity), execute (code execution), logs (runtime output), scripts (source decompilation), and network (traffic capture). Descriptions explicitly differentiate overlapping areas like execute's immediate output vs logs' deferred console, leaving no ambiguity in tool selection.
All names are lowercase single words without underscores or camelCase, following a consistent format. Minor deviation: 'execute' is a verb while the others are nouns, but the uniform style keeps the set predictable.
Six composite tools with sub-actions (list/search/read for scripts; start/stop/read for network) provide a well-scoped surface for a focused Roblox executor. Each tool earns its place, and the count sits comfortably within the 3–15 ideal range.
The set covers connection status, code execution, log inspection, script decompilation/search/read, network capture, and visual verification—a near-complete client-side lifecycle. Minor gaps include no direct script writing/editing tool or instance management beyond status, but execute can work around these.
Maintenance
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
AI Agent Utility Layer for agent safety, web monitoring, crypto research and tool discovery.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to interact with a running Roblox game client to execute Lua code, inspect scripts, spy on remotes, and more.129 npm216MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to interact with a running Roblox game client, including executing Lua code, inspecting scripts, searching instances, intercepting remote events via Sigma Spy, and controlling the GUI.129 npm1MIT
- -licenseNot gradedqualityNot gradedmaintenanceLets AI agents interact with a live Roblox game via an executor, supporting multi-agent sessions and tools for executing Lua, decompiling scripts, exploring game instances, and capturing screenshots.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to inspect and control a live Roblox client through an executor, including reading console output, exploring the instance tree, decompiling scripts, monitoring remote traffic, and running Luau code.MIT