Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Chrrxs/robloxstudio-mcp/llms.txt

Use this file to discover all available pages before exploring further.

Working on a large Roblox place often means the same operation needs to be applied to dozens or hundreds of instances at once — replacing a deprecated API call in every script, setting Transparency on every part in a section of the map, or spawning a grid of NPCs for a stress test. Roblox Studio MCP provides a set of bulk operation tools that perform these tasks in a single call, avoiding the round-trip overhead of looping through instances one by one.

​
Script refactoring workflow

Use grep_scripts and find_and_replace_in_scripts together to locate and replace patterns across every script in a place.
1

Find all usages with grep_scripts

Search the entire place for the deprecated API call. filesOnly=true returns a compact list of script paths so you can see scope before reading any source.
grep_scripts pattern="Instance.new"
             caseSensitive=false
             filesOnly=true
For more precise matching, enable Lua pattern mode with usePattern=true. For example, to find both game:GetService and game.GetService:
grep_scripts pattern="game:GetService|game%.GetService"
             usePattern=true
             caseSensitive=true
             filesOnly=false
             contextLines=2
Results are grouped by script with line and column numbers.
2

Review matches in context

For scripts that show hits, read a line range around the match to understand the surrounding logic before making changes:
get_script_source instancePath="game.ServerScriptService.Legacy.PlayerHandler"
                  line_range="88-110"
3

Dry-run the replacement

Preview the replacement without writing any changes. dryRun=true returns a diff-style summary of what would change.
find_and_replace_in_scripts pattern="workspace:WaitForChild"
                             replacement="game.Workspace:WaitForChild"
                             dryRun=true
Use maxReplacements as a safety limit to avoid accidentally rewriting more instances than intended:
find_and_replace_in_scripts pattern="game:GetService(\"Players\")"
                             replacement="Players"
                             dryRun=true
                             maxReplacements=10
When using Lua pattern matching (usePattern=true), you must also pass caseSensitive=true. Lua pattern mode is always case-sensitive and the tool rejects usePattern=true with caseSensitive=false (or unset). This constraint also applies to grep_scripts when usePattern=true.
4

Apply the replacement

Once the dry-run output looks correct, run without dryRun to write the changes:
find_and_replace_in_scripts pattern="workspace:WaitForChild"
                             replacement="game.Workspace:WaitForChild"
                             dryRun=false
5

Verify with grep_scripts

Re-run the original search to confirm no matches remain:
grep_scripts pattern="workspace:WaitForChild"
             caseSensitive=false
A result with zero matches confirms the refactor is complete.
Always use maxReplacements when running find_and_replace_in_scripts on a pattern that could match more broadly than intended. Setting it to a low value like 5 lets you inspect results in smaller batches and reduces the blast radius of an overly-greedy pattern.

​
Mass property changes

When you need to set the same property on many instances at once, mass_set_property accepts a paths array and applies the value to all of them in one call. Read before writing: Use mass_get_property first to audit current values: 
mass_get_property paths=["game.Workspace.MapSection.Part1",
                          "game.Workspace.MapSection.Part2",
                          "game.Workspace.MapSection.Part3"]
                  propertyName="Transparency"
Apply the change: Set Transparency to 0.5 on 200 parts in a single call: 
mass_set_property paths=["game.Workspace.MapSection.Part1",
                          "game.Workspace.MapSection.Part2",
                          ...
                          "game.Workspace.MapSection.Part200"]
                  propertyName="Transparency"
                  propertyValue=0.5
For complex value types, pass an object: 
mass_set_property paths=["game.Workspace.Barrier.Front",
                          "game.Workspace.Barrier.Back"]
                  propertyName="Color"
                  propertyValue={"r": 1, "g": 0, "b": 0}

​
Batch instance creation

​
Spawn a grid of NPCs with smart_duplicate

smart_duplicate creates count copies of an instance with per-copy position, rotation, or property variations. The positionOffset option shifts each subsequent copy by a fixed [X, Y, Z] delta, making grids and rows straightforward. Create a 10×5 NPC grid (50 total) spaced 8 studs apart on X and 8 studs on Z: 
smart_duplicate instancePath="game.Workspace.NPCTemplate"
                count=50
                options={
                  "namePattern": "NPC_{n}",
                  "positionOffset": [8, 0, 0],
                  "propertyVariations": {
                    "Name": ["NPC_1", "NPC_2", ...]
                  }
                }
For a proper 2D grid, use mass_duplicate to run multiple smart_duplicate operations in one call — one per row — each with a different Z origin.

​
Create instances with different properties using mass_create_objects

mass_create_objects creates multiple instances in one round-trip, each with its own className, parent, name, and properties: 
mass_create_objects objects=[
  {
    "className": "Part",
    "parent": "game.Workspace.Obstacles",
    "name": "Spike_1",
    "properties": {"Size": [1, 4, 1], "Anchored": true, "BrickColor": "Bright red"}
  },
  {
    "className": "Part",
    "parent": "game.Workspace.Obstacles",
    "name": "Spike_2",
    "properties": {"Size": [1, 4, 1], "Anchored": true, "BrickColor": "Bright red"}
  }
]
This is faster than calling create_object twenty times because each call is one Studio round-trip.

​
Bulk attributes

Set multiple attributes on a single instance in one call using bulk_set_attributes. This is more efficient than calling set_attribute repeatedly and is useful for writing gameplay metadata such as faction identifiers, spawn priorities, or damage multipliers. 
bulk_set_attributes instancePath="game.Workspace.Zone.A"
                    attributes={"Faction": "Red", "SpawnPriority": 1}
To apply the same attributes to multiple instances, call bulk_set_attributes once per instance. To verify attributes were written, use get_attributes: 
get_attributes instancePath="game.Workspace.Zone.A"

​
Performance tips

  • Bulk operations save round-trips. Every tool call crosses the MCP server → Studio plugin boundary. A single mass_set_property call on 200 paths is far faster than 200 individual set_property calls.
  • Use filesOnly=true on grep_scripts first. Getting a list of affected script paths is cheap. Only fetch full source with get_script_source for the scripts you plan to edit.
  • Use dryRun=true before every find_and_replace_in_scripts run. The dry-run result is your chance to catch a pattern that matches more broadly than expected.
  • Use maxReplacements as a safety limit. Set it conservatively when experimenting with a new pattern; raise it once you are confident in the scope.
  • Prefer edit_script_lines over set_script_source for targeted changes. Replacing the entire source of a large script is slower and harder to review than a surgical old_string → new_string replacement.

Build docs developers (and LLMs) love

Get started for freeTalk to us