Roblox Studio 的 Vibe Blocks MCP
通过模型上下文协议 (MCP) 将 Roblox Studio 连接到 AI 编码编辑器（如 Cursor、Windsurf、Claude 等），从而实现 Roblox Studio 环境中的 AI 辅助游戏开发。
概述
该项目主要由两部分组成：
**Python MCP 服务器：**一个在本地运行的 FastAPI 服务器。它通过 MCP（使用服务器发送事件 - SSE）将 Roblox Studio 操作作为工具公开。如果已配置，它可以选择性地与 Roblox Open Cloud API 进行交互。
Lua Companion 插件： Roblox Studio 插件 (
roblox_mcp_plugin/src/Plugin.server.lua)，在 Studio 内部运行。它会轮询本地 Python 服务器以获取命令，在 Studio 环境中执行这些命令（操作实例、读取属性、执行 Luau），并将结果和 Studio 日志发送回服务器。
这使得通过 MCP 连接的 AI 代理能够理解并与您的实时 Roblox Studio 会话进行交互。
Related MCP server: Tripo MCP Server
特征
现场演播室互动：
**场景操作：**直接在 Studio 场景中创建、删除、克隆、移动、缩放和设置对象（部件、模型、脚本等）的属性（包括 PrimaryPart）。
**场景检查：**获取对象属性、列出子对象、在 Studio 中按类别或名称查找实例。
**脚本：**创建、编辑和删除脚本/本地脚本。直接在 Studio 环境中执行任意 Luau 代码并捕获输出/错误。
**环境：**设置照明或地形服务的属性。
**动画：**在 Humanoids/AnimationControllers 上播放动画。
**NPC：**通过克隆现有模板或从资产 ID 插入来生成 NPC。
**修改子项：**根据过滤器将属性更改应用于对象的多个子项。
**Studio 日志：**从 Studio 输出窗口检索最近的日志。
Roblox 开放云集成（可选 - 需要 API 密钥）：
**Luau 执行（云）：**在单独的云环境中运行 Luau 代码（对于不需要实时 Studio 访问的任务很有用）。
**数据存储：**列出存储，获取、设置和删除标准数据存储中的键值条目。
**资产：**从本地文件上传新资产（模型、图像、音频）。
**发布：**发布某个地点当前保存或发布的版本。
**（计划）：**获取资产详情，列出用户资产。
设置
1. 先决条件：
Python >= 3.10
uv包管理器（安装 uv ）。强烈建议使用这个，以便更快地管理依赖项。Roblox工作室
**（可选）**用于 Open Cloud 功能的 Roblox API 密钥。请前往Roblox Creator 控制面板 > 凭据 获取。您需要获得所需 API 的权限（例如数据存储、资源上传、发布、Luau 执行等）。
**（可选）**您的 Roblox Universe ID 和目标地点 ID（开放云功能所需）。
2.克隆存储库：
3.安装依赖项：
使用uv （推荐）：
或者，使用pip ：
4.配置环境（可选 - 对于云功能）：
如果您计划使用 Open Cloud 工具（DataStores、Asset Upload、Publishing、Cloud Luau），请复制示例环境文件：
cp .env.example .env编辑
用您的 Roblox API 密钥替换
"YOUR_API_KEY_HERE"。将
ROBLOX_UNIVERSE_ID中的0替换为您的 Universe ID。将
ROBLOX_PLACE_ID中的0替换为目标地点 ID。
**如果您不需要云功能，可以跳过创建
.env文件。**服务器仍会运行，但与云相关的工具将返回错误。
5.在 Roblox Studio 中安装 Companion 插件：
**安装 Rojo：**如果您尚未安装 Rojo，请按照Rojo 网站上的说明进行操作。
**构建插件（可选）：**导航到终端中的
roblox_mcp_plugin目录并运行：rojo build default.project.json --output VibeBlocksMCP_Companion.rbxm这将创建一个
VibeBlocksMCP_Companion.rbxm文件，或者您可以使用存储库中提供的文件。在 Studio 中安装：
找到您的 Roblox Studio 插件文件夹：
Windows：
%LOCALAPPDATA%\Roblox\PluginsmacOS：
~/Documents/Roblox/Plugins（您可能需要在 Finder 中使用Cmd+Shift+G并粘贴路径以导航到那里，或者单击 Roblox Studio 中的插件文件夹）。
将生成的
VibeBlocksMCP_Companion.rbxm文件移动或复制到此插件文件夹中。
**重新启动 Roblox Studio：**现在，当您打开 Studio 时，插件应该会自动加载。
**注意：**该插件会轮询
http://localhost:8000/plugin_command。如果您更改了服务器端口，则需要更新 Lua 脚本 (roblox_mcp_plugin/src/Plugin.server.lua) 顶部的SERVER_URL变量，并重新构建插件。
6.运行Python服务器：
在项目的根目录中打开终端。
使服务器脚本可执行（如果还没有）：
chmod +x server.sh运行服务器：
./server.sh服务器将启动，如果需要，检查/安装
uvicorn，并记录它在http://localhost:8000上运行。使用该服务时，请保持此终端窗口打开。
7. 从 MCP 客户端（例如 Cursor）连接：
该服务可与任何通过服务器发送事件 (SSE) 支持模型上下文协议 (MCP) 的 AI 客户端配合使用，例如 Cursor、Windsurf 或 Claude Desktop 的未来版本。
使用游标的示例：
转到
File > Settings > MCP（或 Mac 上的Code > Settings > MCP）。点击“添加新的全局 MCP 服务器”。
输入SSE URL：
http://localhost:8000/sse（确保包含尾随的/sse）。您可能需要编辑 mcp.json 文件 GXP8
客户端现在应该检测“Vibe Blocks MCP”工具源及其可用工具。
用法
一旦服务器运行，插件安装在 Studio 中，并且您的 MCP 客户端已连接，您就可以通过 AI 与您的 Studio 会话进行交互。
向代理发出请求（如果您的客户需要，请@提及工具，例如list_children ）并要求其执行操作。
示例提示：
在工作区中创建一个名为“Floor”的亮红色部件。将其尺寸设置为 (100, 2, 100)，位置设置为 (0, -1, 0)。将其固定。
“删除名为‘Workspace.OldPlatform’的对象”
“‘Workspace.SpawnLocation’ 的 Position 属性是什么？”
“列出 ServerScriptService 的子项。”
“在 ServerScriptService 下查找所有类名为‘Script’的实例。”
“在 Studio 中执行此脚本：
print(game:GetService('Lighting').ClockTime)”“将 Lighting 的
ClockTime属性设置为 14。”克隆“ReplicatedStorage.Templates.EnemyNPC”，并将其命名为“Guard1”。将其设置为 Workspace 的父级。
“让名为‘Workspace.Guard1’的模型播放动画资产 123456789。”
“修改‘Workspace.DecorationFolder’类名中所有名为‘Part’的子项，将其材质设置为‘Neon’。”
（云示例） “将‘./assets/MyCoolModel.fbx’上传为名为‘Cool Character Model’的模型。”
（云示例） “从‘PlayerData’数据存储中获取键‘player_123_score’的值。”
（云示例） “发布当前地点。”
“显示 Studio 输出的最新日志。”
可用工具
（工具可以直接与 Studio 插件或 Roblox Open Cloud API 交互）
工作室插件工具（实时互动）：
get_property：从 Studio 中的对象检索特定属性的值。list_children：检索 Studio 中对象的直接子对象。find_instances：根据类名或包含 Studio 中的文本的名称在指定的根中查找实例。create_instance：在 Studio 中创建一个新实例（零件、模型、脚本等）。delete_instance：从 Studio 场景中删除一个对象。set_property：在 Studio 中设置对象的特定属性（使用 JSON 字符串作为值）。set_primary_part：设置模型的 PrimaryPart 属性。move_instance：将对象（模型或BasePart）移动到Studio中的新位置。clone_instance：克隆 Studio 中现有的对象。create_script：使用 Studio 中提供的代码创建一个新的 Script 或 LocalScript 实例。edit_script：编辑 Studio 中现有脚本或 LocalScript 的源代码。delete_script：删除 Studio 中现有的脚本或 LocalScript 实例。set_environment：设置 Studio 中的环境服务（照明或地形）的属性。spawn_npc：通过从资产 ID 插入模型或克隆现有模板模型，在 Studio 中生成 NPC。play_animation：在 Studio 中加载并在目标对象的 Humanoid 或 AnimationController 上播放动画。execute_luau_in_studio：通过插件在 LIVE Studio 会话中执行任意 Luau 脚本并捕获输出/返回值/错误。modify_children：查找与可选过滤器（名称/类）匹配的父级下的直接子级，并在其上设置指定的属性。get_studio_logs：通过插件检索从 Roblox Studio 输出窗口捕获的最新日志。
打开云 API 工具（可选 - 需要
execute_luau_in_cloud：通过 Roblox Cloud API 执行任意 Luau 脚本（在单独的云环境中运行，而不是实时 Studio）。list_datastores_in_cloud：通过云 API 列出标准数据存储。get_datastore_value_in_cloud：通过云 API 从标准数据存储中获取条目的值。set_datastore_value_in_cloud：通过云 API 设置标准数据存储区中条目的值。delete_datastore_value_in_cloud：通过云 API 从标准数据存储中删除条目。upload_asset_via_cloud：通过 Cloud API 将文件从本地系统上传为新的 Roblox 资产。publish_place_via_cloud：通过云 API 发布指定地点。get_asset_details_via_cloud：（未实现）通过云 API 获取有关特定资产的详细信息。list_user_assets_via_cloud：（未实现）通过云 API 列出经过身份验证的用户拥有的资产。send_chat_via_cloud：通过云 API（execute_luau）向游戏内聊天发送消息。teleport_player_via_cloud：通过云 API（execute_luau）传送玩家。
内部/排队工具：
queue_studio_command：（低级）为 Studio 插件排队单个原始命令字典。queue_studio_command_batch：（低级）为 Studio 插件排队一批原始命令字典。
故障排除
**服务器未启动：**确保 Python 和
uv已正确安装。检查终端是否有错误信息。确保依赖项已安装（uv pip sync pyproject.toml）。**插件未连接：**验证 Python 服务器是否正在运行。仔细检查 Lua 插件脚本中的
SERVER_URL与服务器地址和端口（默认为http://localhost:8000/plugin_command）是否匹配。检查 Studio 的“输出”窗口，查看插件脚本是否存在错误。**MCP 客户端未连接：**请确保服务器正在运行。请验证 MCP 客户端设置中 SSE URL (
http://localhost:8000/sse) 是否输入正确。**云工具失败：**请确保您已创建包含有效 API 密钥、Universe ID 和 Place ID 的
.env文件。请确保您的 API 密钥拥有您尝试使用的特定云 API 所需的权限。**权限：**如果您从本地文件加载而不是正确安装，则配套插件需要脚本注入权限才能正常运行。