Skip to main content
Glama

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

status

Shows live Roblox instances, their game and player, whether they were kicked, and the decompiler state.

execute

Runs Luau code or a file and returns values, prints, and errors with tracebacks. Runs that time out are cancelled.

logs

Reads the Roblox console, filtered by level, regex, time, or since the last execute.

scripts

Lists, searches, and reads decompiled client scripts, mirrored to .luau files you can grep.

network

Captures remote traffic with arguments, return values, and calling scripts. Hooks exist only while capturing.

screenshot

Captures the Roblox window, even when covered, to check ESP, UI, and menus.

rejoin

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 install

Add 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-lsp

Rebuild 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 tools
executeExecute LuauA

Run Luau in the Roblox client (Opiumware, thread identity 8) and get back return values, print/warn output, and errors with traceback.

  • Just return values; 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 remote gives a per-remote summary (count, rate, latest args); with remote it 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

    A4.4/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      1
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Lets 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.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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