Skip to main content
Glama
okenjioxx

Roblox Executor MCP Server

by okenjioxx
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Run a Luau Script with the Whole Tool Surface (mcp.*) + Persistent VM

script
Destructive

Execute Luau in the active Roblox client with inline access to all MCP tools via an mcp table, enabling one round-trip instead of dozens.

Instructions

Run a Luau program in the active Roblox client that can ALSO call any other tool inline through a live mcp table, and use the results in the same script — one call instead of dozens of round-trips. Inside the script: game, workspace, and all in-game globals are available, PLUS mcp.<tool>(args) invokes any of this server's tools and RETURNS its data. Tool names are camelCase of the tool id (e.g. mcp.getPlayers(), mcp.searchInstances({ className = 'RemoteEvent' }), mcp.findFunctionsByName({ name = 'buy' })), or use mcp.call('kebab-tool-name', { ... }). For N independent calls use mcp.all({ players = { 'get-players' }, remotes = { 'search-instances', { className = 'RemoteEvent' } } }) — runs them all in parallel server-side with a single round-trip and returns a table keyed identically. print/warn are captured and returned as output (and still stream to the dashboard Output console). By default the script runs in a PERSISTENT VM: globals and functions you define survive across script calls (a REPL-like session) — set persistent:false for a clean one-shot, or call vm-reset to wipe the VM. Returns { result = <return value>, output = [lines] } or { error, output }. mcp.script is disabled (no recursion). Signature: { source: string, client: string?, agent: string?, persistent: boolean?, timeoutMs: number?, rpcBudget: number?, threadContext: number? }. Phase: orchestrate; cost=medium; idempotency=contextual-write. Requires: active-client, explicit-mutation-approval, validated-source. Produces: structured-result. Verify with: assert-state. Safety: MUTATING; writes live game/client state. On failure: inspect tool-schema for exact fields, defaults, constraints, and an invocation example.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
agentNoOptional. A stable label for WHICH agent is calling when several share this MCP session (e.g. 'researcher'). Gives that agent its own fair scheduling lane, its own persistent VM on each game, and its own queue budget, so co-tenant agents don't starve or clobber each other.
clientNoOptional. Run on a specific connected client — its clientId OR username — for THIS call only, overriding your session's select-client binding WITHOUT changing it. Lets multiple agents drive different games at the same time; omit to use your session's selected client.
sourceYesThe Luau script to run. Has `game`/`workspace`/all in-game globals, plus `mcp.<tool>(args)` to call any tool and use its returned data inline. `print`/`warn` are captured. `return <value>` to hand a value back.
rpcBudgetNoMax number of `mcp.*` tool calls this script can make through the bridge (default 500). Further calls reject with BUDGET_EXCEEDED so a runaway loop can't saturate the connection.
timeoutMsNoOverall timeout for the whole script including nested tool calls (default 120000).
persistentNoRun in the persistent VM so defined globals/functions survive across calls (default true). false = a fresh, isolated environment each run.
threadContextNoOptional Roblox thread identity for this call; omit it to use the server default.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv2.0.0-spies.2

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only mark it non-read-only, destructive, and non-idempotent; the description adds substantial behavior beyond that: persistent-VM semantics (globals survive across calls, REPL-like), recursion disabled for mcp.script, print/warn capture and streaming, the exact return shapes, cost/idempotency class, mutation-approval and validated-source requirements, and the MUTATING-writes-live-state warning.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core value proposition and then organized into mechanics, return shape, signature, and safety. It is long and repeats some material that also lives in the schema (the trailing Signature line, default values), but most sentences earn their place for such a complex tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return shape itself ({ result, output } / { error, output }) and covers requirements, failure guidance ('inspect tool-schema'), verification (assert-state), and the recursion/budget limits. Nothing an agent needs to call it correctly appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all seven parameters thoroughly, giving a baseline of 3. The description adds value by summarizing the full signature and clarifying behavioral interplay — persistent:false for a one-shot, resetting via vm-reset, and the mcp.all parallel pattern — beyond the raw field definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource (runs a Luau program in the active Roblox client) with a sharp differentiator from siblings like execute/run-luau: it can call any other tool inline via the live `mcp` table and uses a persistent VM. The opening sentence lets an agent distinguish it from the other execution tools without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Strong context for when to reach for it — 'one call instead of dozens of round-trips' for orchestration, and `mcp.all` for N independent calls in a single round-trip. It names vm-reset and persistent:false behaviors, but does not explicitly contrast against the many sibling execution tools (execute, execute-and-wait, batch-execute, eval-expression), nor state a when-not-to-use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools