Kết nối với máy chủ MCP của Roblox Studio | Tài liệu

Máy chủ MCP của Roblox Studio được tích hợp sẵn trong Roblox Studio. Nó thực hiện Mô hình Bối cảnh (MCP), một tiêu chuẩn mở cho phép các công cụ AI giao tiếp an toàn với các ứng dụng bên ngoài. Khi đã kết nối, khách hàng AI của bạn có thể tương tác trực tiếp với phiên Studio đang mở của bạn, khám phá mô hình dữ liệu, viết kịch bản, chạy mã Luau và kiểm tra trải nghiệm của bạn trong chế độ chơi.

Hướng dẫn này chỉ cho bạn cách kết nối máy chủ MCP Studio với các khách hàng AI phổ biến. Mặc dù cách thiết lập khác nhau theo từng khách hàng, nhưng ý tưởng cốt lõi thì vẫn giống nhau: bạn cấu hình khách hàng của mình để kết nối với máy chủ MCP và sau đó gửi lệnh từ khách hàng đến phiên Studio đang hoạt động của bạn.

Các yêu cầu trước

Trước khi bạn có thể kết nối với máy chủ, hãy đảm bảo bạn đã cài đặt phiên bản mới nhất của Roblox Studio và khách hàng MCP mà bạn ưa thích trên máy tính của bạn.

Cách máy chủ MCP Studio hoạt động

Máy chủ chạy như một quy trình cục bộ trên máy của bạn và giao tiếp với khách hàng AI bằng cách sử dụng stdio transport, sử dụng các luồng đầu vào/đầu ra tiêu chuẩn. Tất cả các hành động được khởi xướng thông qua khách hàng AI của bạn, sau đó gửi yêu cầu qua kênh này để thực hiện các hành động bên trong phiên Studio của bạn.

Máy chủ cung cấp các công cụ sau:

Kịch bản
script_read	Đọc một kịch bản từ trò chơi bằng các đường dẫn dot-notation (ví dụ: game.ServerScriptService.MyScript). Hỗ trợ đọc toàn bộ kịch bản hoặc các khoảng dòng cụ thể.
multi_edit	Áp dụng nhiều chỉnh sửa cho một kịch bản trong một thao tác. Nếu đường dẫn mục tiêu không tồn tại, nó sẽ tạo một kịch bản mới. Yêu cầu chỉ định một datamodel_type (Chỉnh sửa).
script_search	Tìm kiếm các kịch bản theo tên bằng cách sử dụng so khớp mờ. Trả về tối đa 10 kết quả.
script_grep	Tìm kiếm một mẫu chuỗi trong tất cả các kịch bản trong trò chơi. Trả về tối đa 50 kết quả phù hợp.
Tạo tài sản và nội dung
generate_mesh	Tạo một lưới 3D có họa tiết từ một lời nhắc văn bản bằng cách sử dụng AI.
generate_material	Tạo một biến thể vật liệu tùy chỉnh. Trả về vật liệu cơ bản và tên biến thể vật liệu để áp dụng cho các bộ phận.
generate_procedural_model	Tạo các đối tượng 3D được xây dựng từ các bộ phận nguyên thủy (khối, hình cầu, hình trụ, hình chóp) dưới dạng ProceduralModel với các thuộc tính có thể cấu hình. Hỗ trợ hình ảnh tham khảo và sơ đồ bộ phận tùy chỉnh.
wait_job_finished	Chờ một công việc tạo mô hình quy trình kết thúc và trả về trạng thái cuối cùng.
search_asset	Tìm kiếm tài sản trên Creator Store (thị trường công khai) và Creator Inventory (người dùng, nhóm hoặc vũ trụ). Hỗ trợ lọc theo loại tài sản, giá, thẻ và phạm vi.
insert_asset	Chèn một tài sản vào trò chơi bằng ID tài sản Roblox số. Hỗ trợ mô hình, lưới, hình ảnh, âm thanh, video, hoạt hình và gói.
upload_image	Tải lên một lô hình ảnh từ các URL HTTP đến máy chủ tài sản Roblox, trả về một đường dẫn hình ảnh đến bản đồ ID tài sản.
store_image	Tải một hình ảnh từ đường dẫn tệp cục bộ và trả về một URI hình ảnh có thể được chuyển cho các công cụ khác (ví dụ: như hình ảnh tham khảo cho generate_procedural_model).
Khám phá mô hình dữ liệu
subagent	Khởi chạy một phụ tác nhân chuyên biệt để xử lý các tác vụ phức tạp, nhiều bước một cách tự động. Các loại có sẵn bao gồm explore (cho việc điều tra mã nguồn và truy vấn trạng thái trò chơi) và playtest (để chạy các kịch bản gameplay và xác minh kết quả).
search_game_tree	Khám phá cấu trúc phân lớp như một mảng JSON phẳng. Hỗ trợ lọc theo đường dẫn, loại thể hiện và từ khóa, với giới hạn độ sâu có thể cấu hình.
inspect_instance	Trả về thông tin chi tiết về một thể hiện cụ thể, bao gồm tất cả các thuộc tính có thể đọc được, thuộc tính tùy chỉnh và tóm tắt về các đối tượng con và hậu duệ của nó.
Thực thi Luau
execute_luau	Chạy mã Luau trong Studio. Trả về hoặc kết quả hoặc lỗi. Yêu cầu chỉ định một datamodel_type (Chỉnh sửa, Khách hàng hoặc Máy chủ).
Kiểm tra thử nghiệm
get_studio_state	Lấy trạng thái hiện tại của Studio, bao gồm trạng thái chơi và các loại datamodel có sẵn.
start_stop_play	Bắt đầu hoặc dừng kiểm tra trải nghiệm chơi.
get_console_output	Lấy đầu ra từ nhật ký đầu ra của Studio.
screen_capture	Chụp ảnh viewport hiện tại của Studio và trả về dữ liệu hình ảnh. Tùy chọn chấp nhận vị trí camera tùy chỉnh và mục tiêu nhìn tới.
Mô phỏng đầu vào người chơi
character_navigation	Di chuyển nhân vật của người chơi đến một vị trí hoặc đường dẫn thể hiện nhất định. Hỗ trợ một hệ số tốc độ có thể cấu hình.
user_keyboard_input	Gửi một hoặc nhiều hành động bàn phím theo thứ tự: nhấn phím, nhả phím, nhấn phím, nhập văn bản hoặc chờ. Hỗ trợ nhắm mục tiêu vào các thể hiện UI cụ thể.
user_mouse_input	Gửi một hoặc nhiều hành động chuột theo thứ tự: di chuyển, nhấp, nhấn nút/nâng nút, cuộn, hoặc chờ. Hỗ trợ nhắm mục tiêu vào các thể hiện hoặc tọa độ màn hình cụ thể.
Tài liệu và kỹ năng
http_get	Lấy nội dung từ các URL tài liệu Roblox được phép (tham chiếu API Engine, tài liệu Creator, Cloud API, hướng dẫn tối ưu hóa hiệu suất). Hỗ trợ tìm kiếm theo từ khóa trong nội dung đã lấy.
skill	Lấy kiến thức chi tiết, thực hành tốt nhất, hoặc tài liệu tham khảo cho các kỹ năng cụ thể như gỡ lỗi, mô phỏng thiết bị, và tìm kiếm tài liệu.
Quản lý phiên
list_roblox_studios	Liệt kê tất cả các phiên Studio đã kết nối, bao gồm tên, ID và trạng thái hoạt động của chúng. Điều này hữu ích khi nhiều cửa sổ Studio đang mở.
set_active_studio	Đặt một thể hiện Studio là hoạt động để tất cả các lệnh công cụ tiếp theo nhắm tới thể hiện đó.

Kích hoạt máy chủ MCP trong Studio

Để kích hoạt máy chủ MCP trong Studio:

Mở Trợ lý.
Nhấp … ⟩ Quản lý máy chủ MCP.
Bật Kích hoạt Studio làm máy chủ MCP.

Sau khi kích hoạt, bảng cài đặt hiển thị tùy chọn kết nối nhanh và hướng dẫn thiết lập cho các khách hàng khác nhau. Khi một khách hàng kết nối thành công, một chỉ báo màu xanh lá cây hiển thị số lượng khách hàng đã kết nối.

Kết nối khách hàng của bạn

Bạn có thể kết nối khách hàng của bạn với máy chủ MCP Studio bằng cách sử dụng kết nối nhanh, một cấu hình JSON, hoặc một lệnh CLI.

Sử dụng kết nối nhanh nếu khách hàng của bạn được hỗ trợ.
Nếu không, hãy sử dụng cấu hình JSON nếu khách hàng của bạn hỗ trợ các tệp cấu hình MCP.
Nếu không, hãy sử dụng một lệnh CLI.

Máy chủ MCP Studio hoạt động với bất kỳ khách hàng nào hỗ trợ stdio transport. Sau khi thêm cấu hình, hãy làm theo tài liệu của khách hàng để hoàn tất thiết lập, sau đó khởi động lại khách hàng để áp dụng thay đổi của bạn.

Các khách hàng MCP có thể đọc và sửa đổi nội dung trong các nơi Roblox mở của bạn. Đảm bảo chỉ kết nối với các khách hàng mà bạn tin tưởng.

Kết nối nhanh

Kết nối nhanh hỗ trợ các khách hàng sau:

Antigravity
Codex CLI
Claude Code
Claude Desktop
Cursor
Gemini CLI
Visual Studio Code

Để kết nối bằng kết nối nhanh:

Đi đến Cài đặt Trợ lý ⟩ Máy chủ MCP.
Mở rộng danh sách thả xuống Kết nối nhanh để xem các khách hàng đã cài đặt trên máy tính của bạn.
Bật khách hàng mà bạn đã chọn.

Nếu khách hàng mà bạn muốn không xuất hiện trong danh sách Kết nối nhanh, hãy cài đặt nó và khởi động lại Roblox Studio.

Cấu hình JSON

Hầu hết các khách hàng MCP hỗ trợ các tệp cấu hình JSON. Các ví dụ sau cho thấy các cấu hình hoàn chỉnh mà bạn có thể sử dụng.

Nếu Roblox Studio là máy chủ MCP duy nhất của bạn, hãy sử dụng các cấu hình này như đã được định dạng. Nếu bạn đang sử dụng nhiều máy chủ MCP, hãy sao chép mục Roblox_Studio và thêm nó vào từ điển mcpServers hiện tại của bạn.

Tệp mcp.json của bạn có thể đã chứa các mục khác. Khi thêm cấu hình Roblox_Studio, hãy đảm bảo mỗi mục được phân tách bằng một dấu phẩy. Nếu thiếu dấu phẩy sẽ dẫn đến JSON không hợp lệ và ngăn cản cấu hình tải lên.

Cấu hình thay đổi theo hệ điều hành:

Windows
{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "cmd.exe",
      "args": [
        "/c",
        "%LOCALAPPDATA%\\Roblox\\mcp.bat"
      ]
    }
  }
}

macOS
{
  "mcpServers": {
    "Roblox_Studio": {
      "command": "/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP"
    }
  }
}

Lệnh CLI

Một số khách hàng MCP yêu cầu một lệnh CLI thay vì cấu hình JSON. Sử dụng lệnh thích hợp cho hệ điều hành của bạn:

Windows
cmd.exe /c %LOCALAPPDATA%\Roblox\mcp.bat

macOS
/Applications/RobloxStudio.app/Contents/MacOS/StudioMCP

Sử dụng nhiều phiên Studio

Bạn có thể kết nối một khách hàng MCP duy nhất với nhiều phiên Studio đang chạy cùng một lúc. Máy chủ tự động xác định phiên nào sẽ sử dụng dựa trên ngữ cảnh (ví dụ: nếu bạn tham chiếu đến một trải nghiệm cụ thể hoặc một đối tượng chỉ tồn tại trong phiên đó).

Bạn có thể chuyển đổi giữa các phiên bằng cách sử dụng list_roblox_studios và set_active_studio.

Xác minh kết nối của bạn

Sau khi thiết lập khách hàng của bạn, hãy xác minh rằng kết nối đang hoạt động trong Roblox Studio:

Mở Trợ lý.
Nhấp … ⟩ Quản lý máy chủ MCP.
Dưới Kích hoạt Studio làm máy chủ MCP, kiểm tra chỉ báo màu xanh lá cây để xác nhận rằng khách hàng đã kết nối thành công.

Khắc phục sự cố

Nếu máy chủ không xuất hiện, hoặc các công cụ không khả dụng:

Khởi động lại cả Roblox Studio và khách hàng MCP của bạn.
Xác minh rằng lệnh hoặc đường dẫn nhị phân là chính xác và tệp tồn tại.
Kiểm tra cú pháp JSON của bạn. Ngay cả việc thiếu một dấu phẩy hoặc dấu ngoặc cũng có thể ngăn cấu hình tải lên.