Purl MCP Server
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., "@Purl MCP Server list all objects in the current project"
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.
Purl MCP Server
MCP server that connects AI assistants to your live Purl Studio project. Read objects, modify scripts, set properties — all from your AI coding tool.
Quick Setup
Claude Code
claude mcp add purl -- npx purl-mcp@latestCursor
Add to .cursor/mcp.json:
{
"mcpServers": {
"purl": {
"command": "npx",
"args": ["purl-mcp@latest"]
}
}
}VS Code
Add to your VS Code settings:
{
"mcp": {
"servers": {
"purl": {
"command": "npx",
"args": ["purl-mcp@latest"]
}
}
}
}Related MCP server: Roblox Studio MCP Bridge
How It Works
The MCP server runs a local WebSocket bridge on port 3001. When you open Purl Studio in your browser, it automatically connects to the bridge. Your AI assistant communicates with the MCP server via stdio, which forwards requests to the browser over WebSocket.
AI Assistant ←stdio→ MCP Server ←WebSocket→ Browser (purl.studio)No API keys, no cloud relay — everything runs locally on your machine.
Tools
Read Tools
Tool | Description |
| Get project structure (cells, settings) |
| List all objects with names, types, tags |
| Get script code for an object or cell |
| Get component states/presets |
| Query Purl DSL documentation |
| Check script syntax for errors |
Write Tools
Tool | Description |
| Set properties on an object (position, size, color, etc.) |
| Replace script code on an object or cell |
| Create a new object in a cell |
| Delete an object |
| Set cell-level properties (gravity, wind, size) |
| Deep-clone an object tree |
| Set properties on multiple objects at once |
Configuration
Environment Variable | Default | Description |
|
| WebSocket server port |
You can also set the port in the browser via URL parameter: https://purl.studio?mcpPort=3002
Requirements
Node.js 18+
A browser with Purl Studio open
Available Tools
26 toolsadd_objectA
Add a new object (prime or component) to a cell. Optionally adds the object as a child of an existing component via parentName. Returns the created object summary.
Inputs: name (required), type (required), prompt (required), cellName (required), +2 more.
bulk_cloneA
Deep-clone one source object into many copies in a single call — the batch counterpart to clone_object. Names come from either an explicit names list or a namePattern containing "{i}" plus a count (if both are given, names wins and the count is its length). Each clone gets fresh unique IDs and collision-safe child renaming, optionally lands inside a component via parentName, and can be offset per-instance via xOffsetPer/yOffsetPer (added as index×offset to the clone and all its descendants). All clones collapse into one undo step.
Inputs: prompt (required), sourceName (required), count, names, +7 more.
bulk_set_propertyA
Set properties on multiple objects in a single call. Useful for mass-editing children of a component (e.g., changing colors). Each entry specifies an object name and properties to set. Same nested-write guards as set_property apply per entry: pass expectedVersion for any property currently holding an array/map and confirmTypeChange:true to allow shape changes.
Inputs: prompt (required), updates (required), cellName.
clear_debug_logsA
Empty the debug log buffer. Use before triggering a test action so the subsequent get_debug_logs call only contains entries from that action.
Inputs: no named parameters.
clone_objectA
Deep-clone an object (with all children, presets, states, scripts) into the same or a different cell. Generates new unique IDs and renames children to avoid name collisions. Optionally lands the clone as a child of an existing component via parentName.
Inputs: prompt (required), newName (required), sourceName (required), cellName, +2 more.
dsl_referenceA
Get reference documentation for the Purl DSL scripting language. Query by category (events, actions, functions, variables, operators, properties, transitions, concepts) or get the full syntax reference. The "concepts" category covers object variables, component child access, message parameters, spawn parameters, and variable scopes.
Inputs: category (required), name.
edit_scriptA
Edit an existing script via a list of find/replace anchors — the safe way to change part of a script without overwriting unrelated lines. Each edit's "old" string must match exactly once in the current content (or set replaceAll: true to replace every occurrence). Edits are applied sequentially in the order supplied; each later edit operates on the result of the previous. Atomic: if any anchor fails to match (zero or multiple), the whole call is rejected with line numbers — nothing is written. Use this for targeted changes; use update_script only for full rewrites or brand-new scripts. Stale baselines fail loudly because the anchor either matches today's content (safe) or doesn't (rejected).
Inputs: edits (required), prompt (required), target (required), cellName, +2 more.
get_debug_logsA
Read recent debug log entries from the running play session. Useful for verifying what the engine saw after a test action (input received? error fired? audio playing?). Only entries for currently-enabled domains exist in the buffer — call set_debug_domains first to enable categories.
Inputs: limit, since, types, domains.
get_objectA
Get full details of a single object — all properties, dynamics config, states, children, scripts. Use this when you need to inspect or debug a specific object.
Inputs: target (required), cellName.
get_projectA
Get the current Purl project structure from the live editor. Returns cells, objects, and settings.
Inputs: no named parameters.
get_scriptB
Get the script code for an object or cell in the current project.
Inputs: target (required), cellName.
get_script_historyA
Get the MCP edit history of a specific script — all past versions written via update_script, most recent last. Use this to recover code that was accidentally wiped by a previous edit. Each entry shows the timestamp, the user prompt that triggered the edit, and the full code snapshot.
Inputs: target (required), limit, cellName, scriptName.
get_statesA
Get presets/states for a component. Returns child list, preset names with per-child property overrides, reference snapshot, and state groups. Only works on components.
Inputs: target (required), cellName.
list_objectsA
List all objects in the current project or a specific cell. Returns names, types, tags, and key properties.
Inputs: cellName.
move_objectA
Reparent an existing object within the same cell. Use newParent: "top" to hoist to cell top level; pass any other string to move into the named component. No-ops when the object is already at the requested parent. Errors if the named parent is not a component, or when trying to move an object into itself.
Inputs: prompt (required), target (required), newParent (required), cellName.
push_valueA
Append a value to an array at a nested path. Additive — only the target array is touched; siblings and unrelated entries stay intact. Errors if the target isn't an array. Use this instead of set_property for adding items to a DATA prime's value (or any other array-shaped property).
Inputs: path (required), value (required), prompt (required), target (required), +2 more.
read_project_scriptsA
Dump every script in the project (cell scripts + object scripts, all tabs) in one call. Use this for whole-project audits, refactors, or "find every place X is wired" questions where you need the surrounding code, not just matching lines (use search_scripts when you only need matching lines). Returns a flat array of {target, scriptName, code, lineCount}, sorted scene-order. Skips empty scripts by default. Soft byte cap (default 50000) bounds the response — if exceeded, returns what fits plus a truncation marker; refine via cellName or targets.
Inputs: targets, cellName, maxBytes, includeEmpty.
remove_objectA
Remove an object from a cell. If the object is a component, its children are also removed.
Inputs: prompt (required), target (required), cellName.
remove_value_at_pathA
Remove a single value at the given path. For arrays, removes the element at the bracket index and shifts subsequent elements down. For maps, deletes the keyed entry. Errors if the path doesn't exist (no silent no-ops).
Inputs: path (required), prompt (required), target (required), cellName, +1 more.
search_scriptsA
Search every script in the project (all cell-script tabs and all object-level scripts, templates included) for a substring. Returns one entry per matching line with target/scriptName/lineNumber/line so the result is directly actionable. Pass contextLines: N to also return the N lines above and below each match — usually enough to skip a follow-up get_script call. Use this whenever you need to answer "where is X used / set / played / spawned / destroyed / handled" before making changes — the only reliable way to enumerate distributed Purl logic.
Inputs: query (required), cellName, contextLines, caseInsensitive.
set_debug_domainsA
Enable a specific set of debug chips on the running play session. Replaces the current set (pass empty array to disable all). Valid domains: collision, movement, follow, dodge, physics, zone, camera, mask, input, audio, errors, log.
Inputs: domains (required).
set_propertyA
Set properties on an object. Merges the given properties into the object. Use for position (x, y), size (width, height), visibility, tags, content (for text), dynamics settings, etc. For nested-shape properties (arrays/maps) the call is guarded: expectedVersion is required to prevent stale-baseline overwrites, and confirmTypeChange is required when the property's shape changes among array/map/scalar. Read with get_object first to obtain _versions.
Inputs: prompt (required), target (required), properties (required), cellName, +2 more.
set_value_at_pathA
Set a single nested value at the given path. Auto-creates intermediate objects/arrays where needed. Siblings stay intact. Use this instead of set_property for changing one field deep in a DATA prime's value (or any other nested property).
Inputs: path (required), value (required), prompt (required), target (required), +2 more.
update_cellC
Set cell-level properties like gravity, wind, windAngle, size, or label.
Inputs: prompt (required), cellName (required), properties (required).
update_scriptA
Full-replace a script: writes the supplied code as the new content. Use for genuine rewrites or to create a new script slot. For incremental edits to an existing script, prefer edit_script — its anchor matching catches stale baselines that update_script would silently overwrite. If you must full-replace an existing script, pass expectedVersion (from get_script or read_project_scripts) so a stale write fails loudly instead of stomping concurrent changes.
Inputs: code (required), prompt (required), target (required), cellName, +3 more.
validate_scriptA
Validate Purl DSL script syntax using the full parser. Returns detailed error messages with line/column numbers, or confirms valid syntax with a summary of detected events and actions.
Inputs: code (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Most tools target distinct resources/actions (e.g., get_object vs list_objects vs get_script), but some overlap exists: get_states duplicates part of get_object, and edit_script/update_script both modify scripts. Descriptions are detailed enough to guide selection, though the boundary between set_property, set_value_at_path, and push_value could confuse an agent at first.
Tool names mostly follow a clear verb_noun pattern (get_, set_, add_, remove_, move_, update_, clone_, bulk_). Minor deviations like 'dsl_reference' (noun phrase) and the path-specific names (set_value_at_path, remove_value_at_path) are still readable and consistent in style. Overall predictable, with slight irregularity.
26 tools is on the heavy side, but the server covers a broad domain (project structure, object lifecycle, scripting, debugging, batch operations). The count feels justified, though the many variations (bulk_*, *_at_path, push_value) inflate the total and could be consolidated without losing clarity.
The tool surface covers the main workflows: object CRUD (add/remove/get/list/clone/move), script management (read/search/edit/update/validate/history), property mutation (set/bulk/path-specific), and debugging (logs/domains). Missing operations like cell creation/deletion or renaming are minor gaps; overall the domain is well covered.
Related MCP Connectors
Gives AI agents direct access to your Sanity projects and guidance for working with them
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Open your team's project from the AI you use: read and write its brief, documents, tasks and notes.
Let your coding agent read your GameSalad projects, and edit them live in Creator on Pro and Edu.
1
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects AI assistants to Roblox Studio, enabling them to interact with instance hierarchy, edit Luau scripts, manage properties, and sync files over a local connection.16 npm2MIT
- AlicenseAqualityDmaintenanceConnects AI coding assistants to Roblox Studio, enabling direct manipulation of the DataModel through natural language commands with undo support.1456 npm2MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to directly manage Roblox Studio projects by creating, reading, updating, and deleting scripts, listing instances, executing Luau code, and inspecting properties. It works through natural language, making Studio operations accessible to AI.-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to explore, edit, and automate Roblox Studio sessions locally, including browsing instance hierarchies, reading and modifying scripts, manipulating properties, creating instances, building terrain, and running playtests.1,057 npmMIT