Roblox MCP Server
Enables AI assistants to inspect the Roblox game hierarchy, read client-side script source code, retrieve instance properties, and execute Lua code directly within a running Roblox client through a WebSocket bridge.
Click on "Install 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., "@Roblox MCP Serverlist the children in Workspace and show me any scripts"
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.
Roblox MCP Server
A Model Context Protocol (MCP) server that acts as a bridge between AI assistants (like Claude/Gemini in IDEs) and a running Roblox instance. This allows the AI to inspect the game hierarchy, read scripts, and execute code directly within the Roblox client.
Architecture
graph LR
IDE["AI / IDE"] <-->|"MCP Protocol (Stdio)"| MCPServer["MCP Server (Node.js)"]
MCPServer <-->|"WebSocket (ws://localhost:3000)"| Roblox["Roblox Client"]
subgraph Roblox Client
Bridge["Bridge.lua"]
Game["Game Engine"]
end
Bridge <--> GameThe system consists of two parts:
MCP Server (
src/): A Node.js application that implements the MCP specification. It hosts a WebSocket server to communicate with Roblox.Roblox Bridge (
roblox/Bridge.lua): A Lua script that runs inside a Roblox executor. It connects to the MCP server via WebSocket and executes commands.
Prerequisites
Node.js: v18 or higher.
Roblox Executor: A Roblox script executor that supports:
WebSocket.connect(or compatibleWebSocketlibrary).getgenv()(optional, for safe environment access).decompile(optional, for reading local scripts).
npm or yarn.
Installation
Clone the repository.
Install dependencies:
npm install
Usage
1. Start the MCP Server
You can run the server in development mode or build it for production.
Development:
# Compile and run
npm run build && npm startThe server will start listening on stdio for MCP connections and ws://localhost:3000 for the Roblox bridge.
2. Inject the Roblox Bridge
Open your Roblox Executor.
Open
roblox/Bridge.lua.Execute the script in the desired Roblox game instance.
Check the executor console (F9) for a connection message:
[MCP-Bridge] Connected!.
Available Tools
The MCP server exposes the following tools to the AI:
list_children
Lists the children of a specific instance.
Arguments:
path(string, e.g., "game.Workspace")Returns: list of
{ name, className, path }
get_properties
Retrieves the properties of a specific instance.
Arguments:
path(string),properties(array of strings, optional)Returns: Map of property names to values.
read_script
Reads the source code of a script.
Arguments:
path(string)Returns: Source code string.
Notes:
Works for
LocalScriptandModuleScript(client-side).Cannot read server-side
Scriptsource due to Roblox replication security (returns empty/error).
run_script
Executes arbitrary Lua code in the context of the bridge script.
Arguments:
code(string)Returns: Array of return values converted to strings.
Troubleshooting
Server Code Access: You cannot read server scripts from the client. This is a Roblox engine limitation, not a bug.
Connection Failed: Ensure port
3000is free and the executor supports WebSockets (most modern ones do).Executor Compatibility: If
WebSocketis not defined, check your executor's documentation. You may need a polyfill.
Available Tools
4 toolsget_propertiesC
Get properties of a Roblox instance
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The path to the instance | |
| properties | No | List of property names to fetch. If omitted, fetches standard properties. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool 'gets' properties, implying a read-only operation, but doesn't specify permissions, rate limits, error handling, or what 'standard properties' entail. This leaves significant gaps in understanding the tool's behavior beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for a tool with two parameters and potential complexity in Roblox instance handling. It doesn't explain return values, error conditions, or behavioral nuances, which are critical for an agent to use the tool effectively in this context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents both parameters ('path' and 'properties') with clear descriptions. The description adds no additional meaning beyond what the schema provides, such as examples or edge cases, but doesn't need to compensate for gaps, resulting in a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and target ('properties of a Roblox instance'), which is specific enough to understand the tool's function. However, it doesn't differentiate from sibling tools like 'read_script' or 'list_children', which might also involve reading instance data, so it doesn't achieve full sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'list_children' or 'read_script'. It lacks context about scenarios where fetching properties is preferred over other operations, leaving the agent to infer usage based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_childrenC
List children of a Roblox instance
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | The path to the instance to list children of (e.g., 'game.Workspace') | game |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool lists children but doesn't describe what 'children' means in this context (e.g., nested instances), whether it's read-only, if there are rate limits, or what the output format looks like. This leaves significant gaps for a tool with no annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It is appropriately sized and front-loaded, making it easy to understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of listing children in a Roblox instance, no annotations, and no output schema, the description is incomplete. It doesn't explain what 'children' entails, the return format, or any behavioral traits like safety or performance considerations, which are crucial for effective tool use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'path' parameter documented as 'The path to the instance to list children of (e.g., 'game.Workspace')'. The description adds no additional meaning beyond this, so it meets the baseline of 3 where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List children') and target resource ('of a Roblox instance'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'get_properties' or 'read_script', which also involve Roblox instances but perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_properties' (which might retrieve properties rather than children) or other sibling tools. It lacks explicit context, prerequisites, or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_scriptA
Read the source code of a script (decompiles if necessary). Note: Cannot read server-side scripts (Script) from a client execution context as their source is not replicated.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The path to the script to read |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses important behavioral traits: decompilation capability and the client/server execution context limitation. However, it doesn't mention permissions needed, rate limits, error conditions, or what happens with invalid paths. The transparency is adequate but incomplete for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences. The first states the core purpose, the second provides crucial exclusion criteria. Every word earns its place, and the most important information (what the tool does) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no annotations and no output schema, the description provides adequate but minimal context. It covers the core functionality and a key limitation, but doesn't address return format, error handling, or authentication requirements. Given the simplicity of the tool, this is minimally viable but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single 'path' parameter. The description doesn't add any additional parameter semantics beyond what the schema provides, such as path format examples or constraints. The baseline of 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'read' and resource 'source code of a script', with additional clarification about decompilation when needed. It distinguishes from sibling tools like 'run_script' by focusing on reading rather than execution, though it doesn't explicitly contrast with 'get_properties' or 'list_children'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when NOT to use this tool: 'Cannot read server-side scripts from a client execution context as their source is not replicated.' This gives important exclusion criteria. However, it doesn't explicitly mention when to choose this tool over alternatives like 'get_properties' for script metadata.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_scriptC
Execute arbitrary Lua code in the Roblox client
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The Lua code to execute |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool executes code, implying it's a mutation/write operation, but doesn't disclose critical traits like security implications, execution environment constraints, error handling, or potential side effects. This is a significant gap for a tool that runs arbitrary code.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with zero wasted words. It's front-loaded with the core purpose and efficiently conveys the essential information without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of executing arbitrary code and the lack of annotations and output schema, the description is incomplete. It doesn't address safety, permissions, return values, or error conditions, which are crucial for an agent to use this tool effectively in a real-world scenario.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'code' clearly documented. The description adds no additional parameter semantics beyond what the schema provides, such as code format examples or execution limits. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Execute') and resource ('arbitrary Lua code in the Roblox client'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'read_script' or 'list_children', which are likely read-only operations, whereas this one executes code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing specific permissions), appropriate contexts, or warnings about misuse, leaving the agent without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
4 tool updates
v1.0.0- First observed
get_properties - First observed
list_children - First observed
read_script - First observed
run_script
TDQS
Each tool has a distinct purpose: get_properties retrieves instance attributes, list_children enumerates child objects, read_script accesses script source code, and run_script executes Lua code. There is no overlap in functionality, making tool selection unambiguous for an agent.
All tool names follow a consistent verb_noun pattern (get_properties, list_children, read_script, run_script) using snake_case. The naming is predictable and readable, with no deviations in style or convention.
With 4 tools, the count is reasonable for a Roblox-focused server, covering core operations like inspection and execution. However, it feels slightly thin, as additional tools for actions like modifying instances or handling events could enhance coverage without being excessive.
The tools provide good read/execute capabilities for Roblox instances and scripts, but there are notable gaps in write operations (e.g., no create, update, or delete tools). This limits agents to inspection and execution without full lifecycle management, which may cause workarounds for more complex tasks.
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Live browser debugging for AI assistants — DOM, console, network via MCP.
Create, test and play AI-native games through server-authoritative contracts.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Connect AI agents to Flato's editable canvas runtime through a hosted MCP server.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/33jrdd/roblox-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server