Bắt đầu sử dụng Unity MCP

• Unity Editor 2022.3 trở lên.
• Git, tải từ git-scm.com. Unity dùng Git ở bước 1 để tải gói. Nếu thiếu Git, Package Manager sẽ dừng với lỗi "No 'git' executable was found". Bạn có thể giữ các tùy chọn mặc định của trình cài đặt. Nếu dùng VCC hoặc ALCOM theo hướng dẫn ở phần tiếp theo thì không cần Git.
• Cách A dùng Claude Desktop vì định dạng tiện ích mở rộng này thuộc Claude Desktop. Ứng dụng có bản cho Windows và macOS. Trên Linux, hãy dùng cách B.
• Dự án phải luôn mở trong Unity Editor khi sử dụng.

Nếu quản lý dự án bằng VRChat Creator Companion (VCC) hoặc ALCOM, hãy cài gói từ kho VPM. Cách này không cần Git. VCC và ALCOM tải gói dưới dạng zip, không gọi Git như Package Manager của Unity.

Liên kết bên dưới mở VCC hoặc ALCOM và yêu cầu bạn xác nhận thêm kho. Nếu dùng VCC, cần phiên bản 2.1.0 trở lên.

Thêm kho Unity MCP

Nếu liên kết không hoạt động, hãy thêm URL này thủ công

https://unity-mcp.shiranui-isuzu.dev/vpm.json

Trong VCC, chọn nút Add Repository trên thẻ Packages của trang Settings. Trong ALCOM, chọn nút Add Repository trên thẻ Repositories của trang Packages. Sau khi thêm kho, Unity MCP xuất hiện trong danh sách gói của dự án. Nếu cài theo cách này, hãy bỏ qua bước đầu của cả cách A và cách B rồi bắt đầu từ bước thứ hai.

• A Cài đặt không dùng dòng lệnh Chỉ cần Unity và Claude Desktop. Bạn không phải gõ lệnh.
• B Dùng dòng lệnh Cài công cụ dòng lệnh để điều khiển Editor từ Claude Code, Cursor, Codex và các ứng dụng khác.

Tổng cộng năm bước, không bước nào cần gõ lệnh.

1. Thêm gói vào Unity

   Trong Unity Editor, mở Window > Package Manager. Nhấn nút + ở góc trên bên trái, chọn Add package from git URL, dán URL bên dưới rồi nhấn Add.

   https://github.com/isuzu-shiranui/UnityMCP.git?path=jp.shiranui-isuzu.unity-mcp

   

   Nếu đã cài bằng VCC hoặc ALCOM ở trên, bạn đã hoàn thành bước này. Hãy chuyển sang bước tiếp theo.

2. Kiểm tra máy chủ đang chạy

   Mở cửa sổ Preferences của Editor và chọn Unity MCP trong danh sách bên trái. Trên Windows, Preferences nằm trong menu Edit. Khi dòng đầu của mục Setup hiển thị "✓ Listening on port", phía Unity đã sẵn sàng.

   Để dùng tiếng Việt, mở Settings ngay trên trang này và chọn Tiếng Việt ở mục Language. Khi đó, dòng trạng thái trong mục Thiết lập sẽ là "✓ Đang lắng nghe trên cổng". Mô tả công cụ và đầu ra CLI vẫn dùng tiếng Anh.

   Máy chủ tự khởi chạy khi mở dự án, bạn không cần khởi chạy thủ công. Cách cài đặt này không cần CLI ở dòng thứ hai.

3. Tải tiện ích mở rộng

   Mở trang Releases trên GitHub và tải tệp isuzu-unity-cli.mcpb.

   

4. Nhấp đúp để cài vào Claude Desktop

   Nhấp đúp vào tệp đã tải để Claude Desktop mở màn hình cài tiện ích mở rộng. Để trống trường tên dự án Unity nếu chỉ có một dự án Unity đang mở.

   Tiện ích dùng chữ ký tự ký. Khi cài đặt, Claude Desktop ghi thông báo về tiện ích chưa được ký vào nhật ký. Điều này không ảnh hưởng đến hoạt động của tiện ích. Bạn cũng có thể kéo tệp vào cửa sổ, hoặc chọn tệp tại Settings > Extensions > Advanced settings > Install Extension.

   Nếu nhấp đúp khiến cửa sổ đóng ngay, đây là hiện tượng đã ghi nhận ở bản Claude Desktop từ Microsoft Store. Đổi phần mở rộng của tệp thành .zip rồi giải nén. Sau đó chọn Install Unpacked Extension trên cùng màn hình và chọn thư mục đã giải nén.

5. Đưa ra yêu cầu

   Giữ dự án mở trong Unity Editor và viết yêu cầu trong Claude Desktop. Các công cụ không hoạt động khi Editor đã đóng.

Cài công cụ dòng lệnh isuzu-unity-cli. Các tệp thực thi là mã máy, nên không cần Node.js hay môi trường chạy .NET.

1. Thêm gói vào Unity

   Giống bước đầu của cách A. Mở Window > Package Manager và dán URL bên dưới vào Add package from git URL.

   https://github.com/isuzu-shiranui/UnityMCP.git?path=jp.shiranui-isuzu.unity-mcp

   Nếu đã cài bằng VCC hoặc ALCOM ở trên, bạn đã hoàn thành bước này. Bạn có thể bật giao diện tiếng Việt tại Preferences > Unity MCP > Settings > Language.

2. Cài công cụ dòng lệnh

   Chạy một dòng lệnh trong terminal.

   Windows (PowerShell)

   irm https://raw.githubusercontent.com/isuzu-shiranui/UnityMCP/main/install.ps1 | iex

   macOS và Linux

   curl -fsSL https://raw.githubusercontent.com/isuzu-shiranui/UnityMCP/main/install.sh | sh

   Nếu đã cài .NET 10 SDK, bạn cũng có thể chạy dotnet tool install -g IsuzuUnityCli. Hoặc tải trực tiếp tệp thực thi từ Releases. Nút Install (Cài đặt) trong Preferences > Unity MCP của Editor cũng thực hiện việc cài CLI.

3. Cài skill cho tác nhân AI

   Lệnh này cài skill cho Claude Code và Codex.

   isuzu-unity-cli setup

4. Đăng ký ứng dụng khách

   Một dòng lệnh đăng ký cả điểm cuối lẫn token. Bạn không cần tự xử lý token.

   isuzu-unity-cli setup --mcp --agent claude-code

   --agent chấp nhận claude-code, claude-desktop, codex, cursor, gemini hoặc vscode. Unity Editor phải đang chạy. Xem toàn bộ lệnh trong tài liệu CLI (tiếng Anh), và cấu hình từng ứng dụng trong Kết nối ứng dụng khách MCP (tiếng Anh).

• Đọc cấu trúc phân cấp scene và tìm GameObject bạn cần.
• Tạo GameObject, thêm component và thay đổi vị trí, góc xoay, tỷ lệ.
• Đọc và ghi các thuộc tính được tuần tự hóa hiển thị trong Inspector.
• Đọc lỗi và cảnh báo trong Console, hoặc đọc trực tiếp Editor.log.
• Chụp Game view hoặc Scene view.
• Đọc và thay đổi giá trị hiện tại của material.
• Bắt đầu và dừng Play Mode.

Công cụ Timeline chỉ xuất hiện khi cài gói Timeline; công cụ Recorder cần cả Recorder lẫn Timeline; công cụ kiểm thử cần Test Framework. Xem danh sách đầy đủ trong tài liệu công cụ (tiếng Anh).

• Unity Editor chưa mở

  Mọi công cụ đều thao tác trên Unity Editor đang chạy, nên sẽ không có phản hồi khi Editor đã đóng. Mở lại dự án và kiểm tra dấu ✓ ở dòng đầu mục Setup (Thiết lập) trong Preferences > Unity MCP.

• Nhiều dự án đang mở

  Khi nhiều Unity Editor cùng chạy, tiện ích chưa biết cần kết nối dự án nào. Điền tên trên thanh tiêu đề của Editor vào trường tên dự án trong cài đặt tiện ích. Bạn cũng có thể dùng Product Name trong Player Settings. Nếu cả hai tên vẫn khớp nhiều Editor, hãy đóng các Editor còn lại để chọn đúng dự án.

  Xem cấu hình từng ứng dụng khách (tiếng Anh)

• Không thấy công cụ

  Thêm hoặc xóa gói làm thay đổi danh sách công cụ, nhưng ứng dụng khách không nhận được thông báo về thay đổi đó. Hãy kết nối lại ứng dụng khách đang dùng.

  Xem cách khắc phục sự cố (tiếng Anh)