Roblox Studio MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/tools/index.ts:61-75 (handler)

  The handler function that implements the core logic of the 'search_objects' tool. It sends a request to the Studio bridge API endpoint '/api/search-objects' with the provided query, searchType, and optional propertyName, then returns the formatted JSON response.
  async searchObjects(query: string, searchType: string = 'name', propertyName?: string) { const response = await this.client.request('/api/search-objects', { query, searchType, propertyName }); return { content: [ { type: 'text', text: JSON.stringify(response, null, 2) } ] }; }
• src/index.ts:116-137 (schema)

  The schema definition for the 'search_objects' tool, including input parameters, types, descriptions, and requirements, provided in the MCP listTools response.
  name: 'search_objects', description: 'Find instances by name, class, or properties', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query' }, searchType: { type: 'string', enum: ['name', 'class', 'property'], description: 'Type of search to perform', default: 'name' }, propertyName: { type: 'string', description: 'Property name when searchType is "property"' } }, required: ['query'] }
• src/index.ts:658-659 (registration)

  Registration and dispatch logic in the MCP CallToolRequest handler that routes 'search_objects' calls to the tools.searchObjects method with appropriate argument parsing.
  case 'search_objects': return await this.tools.searchObjects((args as any)?.query as string, (args as any)?.searchType || 'name', (args as any)?.propertyName);
• src/index.ts:55-640 (registration)

  The listTools request handler that registers 'search_objects' by including it in the tools list returned to MCP clients.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ // File System Tools { name: 'get_file_tree', description: 'Get complete hierarchy of the Roblox Studio project with script types, models, and folders', inputSchema: { type: 'object', properties: { path: { type: 'string', description: 'Optional path to start from (defaults to workspace root)', default: '' } } } }, { name: 'search_files', description: 'Find files by name, type, or content patterns', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query (name, type, or content pattern)' }, searchType: { type: 'string', enum: ['name', 'type', 'content'], description: 'Type of search to perform', default: 'name' } }, required: ['query'] } }, // Studio Context Tools { name: 'get_place_info', description: 'Get place ID, name, and game settings', inputSchema: { type: 'object', properties: {} } }, { name: 'get_services', description: 'Get available Roblox services and their children', inputSchema: { type: 'object', properties: { serviceName: { type: 'string', description: 'Optional specific service name to query' } } } }, { name: 'search_objects', description: 'Find instances by name, class, or properties', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Search query' }, searchType: { type: 'string', enum: ['name', 'class', 'property'], description: 'Type of search to perform', default: 'name' }, propertyName: { type: 'string', description: 'Property name when searchType is "property"' } }, required: ['query'] } }, // Property & Instance Tools { name: 'get_instance_properties', description: 'Get all properties of a specific instance', inputSchema: { type: 'object', properties: { instancePath: { type: 'string', description: 'Path to the instance' } }, required: ['instancePath'] } }, { name: 'get_instance_children', description: 'Get child objects and their types', inputSchema: { type: 'object', properties: { instancePath: { type: 'string', description: 'Path to the parent instance' } }, required: ['instancePath'] } }, { name: 'search_by_property', description: 'Find objects with specific property values', inputSchema: { type: 'object', properties: { propertyName: { type: 'string', description: 'Name of the property to search' }, propertyValue: { type: 'string', description: 'Value to search for' } }, required: ['propertyName', 'propertyValue'] } }, { name: 'get_class_info', description: 'Get available properties/methods for Roblox classes', inputSchema: { type: 'object', properties: { className: { type: 'string', description: 'Roblox class name' } }, required: ['className'] } }, // Project Tools { name: 'get_project_structure', description: 'Get complete game hierarchy. IMPORTANT: Use maxDepth parameter (default: 3) to explore deeper levels of the hierarchy. Set higher values like 5-10 for comprehensive exploration', inputSchema: { type: 'object', properties: { path: { type: 'string', description: 'Optional path to start from (defaults to workspace root)', default: '' }, maxDepth: { type: 'number', description: 'Maximum depth to traverse (default: 3). RECOMMENDED: Use 5-10 for thorough exploration. Higher values provide more complete structure', default: 3 }, scriptsOnly: { type: 'boolean', description: 'Show only scripts and script containers', default: false } } } }, // Property Modification Tools { name: 'set_property', description: 'Set a property on any Roblox instance', inputSchema: { type: 'object', properties: { instancePath: { type: 'string', description: 'Path to the instance (e.g., "game.Workspace.Part")' }, propertyName: { type: 'string', description: 'Name of the property to set' }, propertyValue: { description: 'Value to set the property to (any type)' } }, required: ['instancePath', 'propertyName', 'propertyValue'] } }, { name: 'mass_set_property', description: 'Set the same property on multiple instances at once', inputSchema: { type: 'object', properties: { paths: { type: 'array', items: { type: 'string' }, description: 'Array of instance paths to modify' }, propertyName: { type: 'string', description: 'Name of the property to set' }, propertyValue: { description: 'Value to set the property to (any type)' } }, required: ['paths', 'propertyName', 'propertyValue'] } }, { name: 'mass_get_property', description: 'Get the same property from multiple instances at once', inputSchema: { type: 'object', properties: { paths: { type: 'array', items: { type: 'string' }, description: 'Array of instance paths to read from' }, propertyName: { type: 'string', description: 'Name of the property to get' } }, required: ['paths', 'propertyName'] } }, // Object Creation/Deletion Tools { name: 'create_object', description: 'Create a new Roblox object instance (basic, without properties)', inputSchema: { type: 'object', properties: { className: { type: 'string', description: 'Roblox class name (e.g., "Part", "Script", "Folder")' }, parent: { type: 'string', description: 'Path to the parent instance (e.g., "game.Workspace")' }, name: { type: 'string', description: 'Optional name for the new object' } }, required: ['className', 'parent'] } }, { name: 'create_object_with_properties', description: 'Create a new Roblox object instance with initial properties', inputSchema: { type: 'object', properties: { className: { type: 'string', description: 'Roblox class name (e.g., "Part", "Script", "Folder")' }, parent: { type: 'string', description: 'Path to the parent instance (e.g., "game.Workspace")' }, name: { type: 'string', description: 'Optional name for the new object' }, properties: { type: 'object', description: 'Properties to set on creation' } }, required: ['className', 'parent'] } }, { name: 'mass_create_objects', description: 'Create multiple objects at once (basic, without properties)', inputSchema: { type: 'object', properties: { objects: { type: 'array', items: { type: 'object', properties: { className: { type: 'string', description: 'Roblox class name' }, parent: { type: 'string', description: 'Path to the parent instance' }, name: { type: 'string', description: 'Optional name for the object' } }, required: ['className', 'parent'] }, description: 'Array of objects to create' } }, required: ['objects'] } }, { name: 'mass_create_objects_with_properties', description: 'Create multiple objects at once with initial properties', inputSchema: { type: 'object', properties: { objects: { type: 'array', items: { type: 'object', properties: { className: { type: 'string', description: 'Roblox class name' }, parent: { type: 'string', description: 'Path to the parent instance' }, name: { type: 'string', description: 'Optional name for the object' }, properties: { type: 'object', description: 'Properties to set on creation' } }, required: ['className', 'parent'] }, description: 'Array of objects to create with properties' } }, required: ['objects'] } }, { name: 'delete_object', description: 'Delete a Roblox object instance', inputSchema: { type: 'object', properties: { instancePath: { type: 'string', description: 'Path to the instance to delete' } }, required: ['instancePath'] } }, // Smart Duplication Tools { name: 'smart_duplicate', description: 'Smart duplication with automatic naming, positioning, and property variations', inputSchema: { type: 'object', properties: { instancePath: { type: 'string', description: 'Path to the instance to duplicate' }, count: { type: 'number', description: 'Number of duplicates to create' }, options: { type: 'object', properties: { namePattern: { type: 'string', description: 'Name pattern with {n} placeholder (e.g., "Button{n}")' }, positionOffset: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3, description: 'X, Y, Z offset per duplicate' }, rotationOffset: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3, description: 'X, Y, Z rotation offset per duplicate' }, scaleOffset: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3, description: 'X, Y, Z scale multiplier per duplicate' }, propertyVariations: { type: 'object', description: 'Property name to array of values' }, targetParents: { type: 'array', items: { type: 'string' }, description: 'Different parent for each duplicate' } } } }, required: ['instancePath', 'count'] } }, { name: 'mass_duplicate', description: 'Perform multiple smart duplications at once', inputSchema: { type: 'object', properties: { duplications: { type: 'array', items: { type: 'object', properties: { instancePath: { type: 'string', description: 'Path to the instance to duplicate' }, count: { type: 'number', description: 'Number of duplicates to create' }, options: { type: 'object', properties: { namePattern: { type: 'string', description: 'Name pattern with {n} placeholder' }, positionOffset: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3, description: 'X, Y, Z offset per duplicate' }, rotationOffset: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3, description: 'X, Y, Z rotation offset per duplicate' }, scaleOffset: { type: 'array', items: { type: 'number' }, minItems: 3, maxItems: 3, description: 'X, Y, Z scale multiplier per duplicate' }, propertyVariations: { type: 'object', description: 'Property name to array of values' }, targetParents: { type: 'array', items: { type: 'string' }, description: 'Different parent for each duplicate' } } } }, required: ['instancePath', 'count'] }, description: 'Array of duplication operations' } }, required: ['duplications'] } }, // Calculated Property Tools { name: 'set_calculated_property', description: 'Set properties using mathematical formulas and variables', inputSchema: { type: 'object', properties: { paths: { type: 'array', items: { type: 'string' }, description: 'Array of instance paths to modify' }, propertyName: { type: 'string', description: 'Name of the property to set' }, formula: { type: 'string', description: 'Mathematical formula (e.g., "Position.magnitude * 2", "index * 50")' }, variables: { type: 'object', description: 'Additional variables for the formula' } }, required: ['paths', 'propertyName', 'formula'] } }, // Relative Property Tools { name: 'set_relative_property', description: 'Modify properties relative to their current values', inputSchema: { type: 'object', properties: { paths: { type: 'array', items: { type: 'string' }, description: 'Array of instance paths to modify' }, propertyName: { type: 'string', description: 'Name of the property to modify' }, operation: { type: 'string', enum: ['add', 'multiply', 'divide', 'subtract', 'power'], description: 'Mathematical operation to perform' }, value: { description: 'Value to use in the operation' }, component: { type: 'string', enum: ['X', 'Y', 'Z'], description: 'Specific component for Vector3/UDim2 properties' } }, required: ['paths', 'propertyName', 'operation', 'value'] } }, // Script Management Tools { name: 'get_script_source', description: 'Get the source code of a script object (LocalScript, Script, or ModuleScript)', inputSchema: { type: 'object', properties: { instancePath: { type: 'string', description: 'Path to the script instance (e.g., "game.ServerScriptService.MainScript")' } }, required: ['instancePath'] } }, { name: 'set_script_source', description: 'Safely set the source code of a script object without using loadstring (Studio only)', inputSchema: { type: 'object', properties: { instancePath: { type: 'string', description: 'Path to the script instance (e.g., "game.ServerScriptService.MainScript")' }, source: { type: 'string', description: 'New source code for the script' } }, required: ['instancePath', 'source'] } } ] }; });
• src/http-server.ts:177-184 (helper)

  HTTP proxy endpoint for direct calls to search_objects tool from the Studio plugin bridge.
  app.post('/mcp/search_objects', async (req, res) => { try { const result = await tools.searchObjects(req.body.query, req.body.searchType, req.body.propertyName); res.json(result); } catch (error) { res.status(500).json({ error: error instanceof Error ? error.message : 'Unknown error' }); } });