From 68fbd82d78623e9a9b588227faeae44719e67287 Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Sun, 5 Oct 2025 18:13:44 +0200 Subject: [PATCH] feat: scirpt for installing unity mcp --- install_unity_mcp.sh | 231 +++++++++++++++++++++++++++++++++++++++++++ mcp_readme.md | 189 +++++++++++++++++++++++++++++++++++ 2 files changed, 420 insertions(+) create mode 100755 install_unity_mcp.sh create mode 100644 mcp_readme.md diff --git a/install_unity_mcp.sh b/install_unity_mcp.sh new file mode 100755 index 0000000..6fd34c7 --- /dev/null +++ b/install_unity_mcp.sh @@ -0,0 +1,231 @@ +#!/usr/bin/env bash + +set -euo pipefail + +SCRIPT_NAME="$(basename "$0")" + +RED="\033[31m" +YELLOW="\033[33m" +BLUE="\033[34m" +RESET="\033[0m" + +info() { + printf "%b[%s]%b %s\n" "$BLUE" "$SCRIPT_NAME" "$RESET" "$*" +} + +warn() { + printf "%b[%s]%b %s\n" "$YELLOW" "$SCRIPT_NAME" "$RESET" "$*" >&2 +} + +error() { + printf "%b[%s]%b %s\n" "$RED" "$SCRIPT_NAME" "$RESET" "$*" >&2 +} + +require_command() { + local cmd="$1" + local package_hint="${2:-}" + + if ! command -v "$cmd" >/dev/null 2>&1; then + if [[ -n "$package_hint" ]]; then + error "Missing command '$cmd'. Try installing the package: $package_hint" + else + error "Missing command '$cmd'." + fi + exit 1 + fi +} + +ensure_pacman_packages() { + local packages=("python" "git" "curl" "jq" "code") + local missing=() + for pkg in "${packages[@]}"; do + if ! pacman -Qi "$pkg" >/dev/null 2>&1; then + missing+=("$pkg") + fi + done + + if (( ${#missing[@]} > 0 )); then + info "Installing required packages with pacman: ${missing[*]}" + sudo pacman -S --needed --noconfirm "${missing[@]}" + else + info "All required pacman packages are already installed." + fi +} + +install_uv() { + if command -v uv >/dev/null 2>&1; then + info "uv is already installed." + return + fi + + info "Installing uv toolchain manager via official installer." + curl -LsSf https://astral.sh/uv/install.sh | sh + + local local_bin="$HOME/.local/bin" + if [[ ":$PATH:" != *":$local_bin:"* ]]; then + warn "Adding $local_bin to PATH in ~/.profile and ~/.zshrc. Open a new shell to apply." + printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$HOME/.profile" + printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$HOME/.zshrc" + fi +} + +ensure_unity_hub() { + if command -v unityhub >/dev/null 2>&1; then + info "Unity Hub already installed." + return + fi + + if command -v yay >/dev/null 2>&1; then + info "Installing Unity Hub from AUR using yay." + yay -S --needed --noconfirm unityhub + elif command -v flatpak >/dev/null 2>&1; then + warn "Unity Hub not found. Attempting Flatpak installation." + flatpak install -y com.unity.UnityHub || warn "Flatpak installation failed. Install Unity Hub manually via https://unity.com/download" + else + warn "Unity Hub not found and neither yay nor flatpak is available. Install Unity Hub manually from https://unity.com/download." + fi +} + +sync_unity_mcp_repo() { + local data_home="${XDG_DATA_HOME:-$HOME/.local/share}" + local unity_mcp_root="$data_home/UnityMCP" + local repo_dir="$unity_mcp_root/unity-mcp-repo" + local server_link="$unity_mcp_root/UnityMcpServer" + local candidates=( + "UnityMcpServer" + "UnityMcpBridge/UnityMcpServer" + "UnityMcpBridge/UnityMcpServer~" + ) + local server_subdir="" + + mkdir -p "$unity_mcp_root" + + if [[ -d "$repo_dir/.git" ]]; then + info "Updating existing unity-mcp repository." + git -C "$repo_dir" pull --ff-only + else + info "Cloning unity-mcp repository." + rm -rf "$repo_dir" + git clone --depth=1 https://github.com/CoplayDev/unity-mcp.git "$repo_dir" + fi + + for candidate in "${candidates[@]}"; do + if [[ -d "$repo_dir/$candidate/src" ]]; then + server_subdir="$candidate" + break + fi + done + + if [[ -z "$server_subdir" ]]; then + error "UnityMcpServer src directory not found. Checked candidates: ${candidates[*]}" + error "Repository layout may have changed. Inspect $repo_dir for the new server location." + exit 1 + fi + + ln -sfn "$repo_dir/$server_subdir" "$server_link" + info "UnityMcpServer synchronized at $server_link (source: $server_subdir)" +} + +configure_vscode_mcp() { + local data_home="${XDG_DATA_HOME:-$HOME/.local/share}" + local server_src="$data_home/UnityMCP/UnityMcpServer/src" + local mcp_config_dir="$HOME/.config/Code/User" + local mcp_config="$mcp_config_dir/mcp.json" + local tmp + + if [[ ! -d "$server_src" ]]; then + error "Server source directory $server_src is missing." + exit 1 + fi + + mkdir -p "$mcp_config_dir" + + if [[ ! -f "$mcp_config" ]]; then + info "Creating new VS Code MCP configuration at $mcp_config" + echo '{}' > "$mcp_config" + else + info "Updating existing VS Code MCP configuration at $mcp_config" + fi + + tmp="$(mktemp)" + + if ! jq '.' "$mcp_config" >/dev/null 2>&1; then + error "Existing $mcp_config is not valid JSON. Please fix it before running this script again." + exit 1 + fi + + jq \ + --arg path "$server_src" \ + '(.servers //= {}) | + .servers.unityMCP = { + command: "uv", + args: ["--directory", $path, "run", "server.py"], + type: "stdio" + }' \ + "$mcp_config" > "$tmp" + + mv "$tmp" "$mcp_config" + info "VS Code MCP server configuration updated for UnityMCP." +} + +verify_python_version() { + require_command python "python" + local version + version="$(python - <<'PY' +import sys +print("%d.%d.%d" % sys.version_info[:3]) +PY +)" + local major minor + IFS='.' read -r major minor _ <<< "$version" + if (( major < 3 || (major == 3 && minor < 12) )); then + error "Python 3.12+ is required. Detected version $version. Upgrade python before continuing." + exit 1 + fi + info "Python version $version satisfies requirement (>= 3.12)." +} + +print_next_steps() { + cat <<'EOT' + +Next steps: + 1. Launch Unity Hub and install a Unity Editor version 2021.3 LTS or newer. + 2. Open your Unity project and add the MCP for Unity Bridge package via: + Window > Package Manager > + > Add package from git URL... + https://github.com/CoplayDev/unity-mcp.git?path=/UnityMcpBridge + 3. In Unity, open Window > MCP for Unity and run Auto-Setup. Confirm the status shows Connected ✓. + 4. Open Visual Studio Code. The MCP server entry "unityMCP" is now configured. Reload if prompted. + 5. In VS Code, open the MCP client (e.g., Copilot / Claude Code) and issue a request such as "Create a tic-tac-toe game in 3D". The Unity MCP server should respond by operating inside your Unity project. + +Optional (Roslyn strict validation): + - Install NuGetForUnity and add Microsoft.CodeAnalysis + SQLitePCLRaw packages, then define USE_ROSLYN, OR + - Manually place Roslyn DLLs into Assets/Plugins and add USE_ROSLYN to Scripting Define Symbols. + +Troubleshooting tips: + - If VS Code cannot launch the server, ensure `uv` is on PATH and that ~/.local/bin is exported in your shell. + - To run the server manually: `uv --directory ~/.local/share/UnityMCP/UnityMcpServer/src run server.py` + - Verify the directory path in ~/.config/Code/User/mcp.json matches your installation. + +EOT +} + +main() { + if [[ ! -f /etc/arch-release ]]; then + error "This script is intended for Arch Linux." + exit 1 + fi + + info "Ensuring base dependencies are installed." + require_command sudo "sudo" + require_command pacman "pacman" + ensure_pacman_packages + verify_python_version + install_uv + ensure_unity_hub + sync_unity_mcp_repo + configure_vscode_mcp + print_next_steps + info "Setup complete. Follow the next steps above to finish configuration inside Unity." +} + +main "$@" diff --git a/mcp_readme.md b/mcp_readme.md new file mode 100644 index 0000000..6312f04 --- /dev/null +++ b/mcp_readme.md @@ -0,0 +1,189 @@ +## How It Works + +MCP for Unity connects your tools using two components: + +1. **MCP for Unity Bridge:** A Unity package running inside the Editor. (Installed via Package Manager). +2. **MCP for Unity Server:** A Python server that runs locally, communicating between the Unity Bridge and your MCP Client. (Installed automatically by the package on first run or via Auto-Setup; manual setup is available as a fallback). + +image + +--- + +## Installation ⚙️ + +### Prerequisites + + * **Python:** Version 3.12 or newer. [Download Python](https://www.python.org/downloads/) + * **Unity Hub & Editor:** Version 2021.3 LTS or newer. [Download Unity](https://unity.com/download) + * **uv (Python toolchain manager):** + ```bash + # macOS / Linux + curl -LsSf https://astral.sh/uv/install.sh | sh + + # Windows (PowerShell) + winget install --id=astral-sh.uv -e + + # Docs: https://docs.astral.sh/uv/getting-started/installation/ + ``` + + * **An MCP Client:** : [Claude Desktop](https://claude.ai/download) | [Claude Code](https://github.com/anthropics/claude-code) | [Cursor](https://www.cursor.com/en/downloads) | [Visual Studio Code Copilot](https://code.visualstudio.com/docs/copilot/overview) | [Windsurf](https://windsurf.com) | Others work with manual config + + *
[Optional] Roslyn for Advanced Script Validation + + For **Strict** validation level that catches undefined namespaces, types, and methods: + + **Method 1: NuGet for Unity (Recommended)** + 1. Install [NuGetForUnity](https://github.com/GlitchEnzo/NuGetForUnity) + 2. Go to `Window > NuGet Package Manager` + 3. Search for `Microsoft.CodeAnalysis`, select version 4.14.0, and install the package + 4. Also install package `SQLitePCLRaw.core` and `SQLitePCLRaw.bundle_e_sqlite3`. + 5. Go to `Player Settings > Scripting Define Symbols` + 6. Add `USE_ROSLYN` + 7. Restart Unity + + **Method 2: Manual DLL Installation** + 1. Download Microsoft.CodeAnalysis.CSharp.dll and dependencies from [NuGet](https://www.nuget.org/packages/Microsoft.CodeAnalysis.CSharp/) + 2. Place DLLs in `Assets/Plugins/` folder + 3. Ensure .NET compatibility settings are correct + 4. Add `USE_ROSLYN` to Scripting Define Symbols + 5. Restart Unity + + **Note:** Without Roslyn, script validation falls back to basic structural checks. Roslyn enables full C# compiler diagnostics with precise error reporting.
+ +--- +### 🚀 Arch Linux Quick Setup Script + +If you're on Arch Linux and use Visual Studio Code as your MCP client, run the helper script in `Bash/install_unity_mcp.sh` to install the MCP server dependencies, clone the latest `unity-mcp` repository, and configure `~/.config/Code/User/mcp.json` automatically: + +```bash +chmod +x Bash/install_unity_mcp.sh +./Bash/install_unity_mcp.sh +``` + +The script requires `sudo` access for `pacman` and optionally uses `yay` or `flatpak` to install Unity Hub. After it finishes, continue with the Unity-side steps below to import the MCP for Unity Bridge package inside your project. + +--- +### 🌟 Step 1: Install the Unity Package + +#### To install via Git URL + +1. Open your Unity project. +2. Go to `Window > Package Manager`. +3. Click `+` -> `Add package from git URL...`. +4. Enter: + ``` + https://github.com/CoplayDev/unity-mcp.git?path=/UnityMcpBridge + ``` +5. Click `Add`. +6. The MCP server is installed automatically by the package on first run or via Auto-Setup. If that fails, use Manual Configuration (below). + +#### To install via OpenUPM + +1. Install the [OpenUPM CLI](https://openupm.com/docs/getting-started-cli.html) +2. Open a terminal (PowerShell, Terminal, etc.) and navigate to your Unity project directory +3. Run `openupm add com.coplaydev.unity-mcp` + +**Note:** If you installed the MCP Server before Coplay's maintenance, you will need to uninstall the old package before re-installing the new one. + +### 🛠️ Step 2: Configure Your MCP Client +Connect your MCP Client (Claude, Cursor, etc.) to the Python server set up in Step 1 (auto) or via Manual Configuration (below). + +MCPForUnity-Readme-Image + +**Option A: Auto-Setup (Recommended for Claude/Cursor/VSC Copilot)** + +1. In Unity, go to `Window > MCP for Unity`. +2. Click `Auto-Setup`. +3. Look for a green status indicator 🟢 and "Connected ✓". *(This attempts to modify the MCP Client's config file automatically).* + +
Client-specific troubleshooting + + - **VSCode**: uses `Code/User/mcp.json` with top-level `servers.unityMCP` and `"type": "stdio"`. On Windows, MCP for Unity writes an absolute `uv.exe` (prefers WinGet Links shim) to avoid PATH issues. + - **Cursor / Windsurf** [(**help link**)](https://github.com/CoplayDev/unity-mcp/wiki/1.-Fix-Unity-MCP-and-Cursor,-VSCode-&-Windsurf): if `uv` is missing, the MCP for Unity window shows "uv Not Found" with a quick [HELP] link and a "Choose `uv` Install Location" button. + - **Claude Code** [(**help link**)](https://github.com/CoplayDev/unity-mcp/wiki/2.-Fix-Unity-MCP-and-Claude-Code): if `claude` isn't found, the window shows "Claude Not Found" with [HELP] and a "Choose Claude Location" button. Unregister now updates the UI immediately.
+ + +**Option B: Manual Configuration** + +If Auto-Setup fails or you use a different client: + +1. **Find your MCP Client's configuration file.** (Check client documentation). + * *Claude Example (macOS):* `~/Library/Application Support/Claude/claude_desktop_config.json` + * *Claude Example (Windows):* `%APPDATA%\Claude\claude_desktop_config.json` +2. **Edit the file** to add/update the `mcpServers` section, using the *exact* paths from Step 1. + +
+Click for Client-Specific JSON Configuration Snippets... + +**VSCode (all OS)** + +```json +{ + "servers": { + "unityMCP": { + "command": "uv", + "args": ["--directory","/UnityMcpServer/src","run","server.py"], + "type": "stdio" + } + } +} +``` + +**Linux:** + +```json +{ + "mcpServers": { + "UnityMCP": { + "command": "uv", + "args": [ + "run", + "--directory", + "/home/YOUR_USERNAME/.local/share/UnityMCP/UnityMcpServer/src", + "server.py" + ] + } + // ... other servers might be here ... + } +} +``` + +(Replace YOUR_USERNAME) + + +
+ +--- + +## Usage ▶️ + +1. **Open your Unity Project.** The MCP for Unity package should connect automatically. Check status via Window > MCP for Unity. + +2. **Start your MCP Client** (Claude, Cursor, etc.). It should automatically launch the MCP for Unity Server (Python) using the configuration from Installation Step 2. + +3. **Interact!** Unity tools should now be available in your MCP Client. + + Example Prompt: `Create a 3D player controller`, `Create a tic-tac-toe game in 3D`, `Create a cool shader and apply to a cube`. + +## Troubleshooting ❓ + +
+Click to view common issues and fixes... + +- **Unity Bridge Not Running/Connecting:** + - Ensure Unity Editor is open. + - Check the status window: Window > MCP for Unity. + - Restart Unity. +- **MCP Client Not Connecting / Server Not Starting:** + - **Verify Server Path:** Double-check the --directory path in your MCP Client's JSON config. It must exactly match the installation location: + - **Windows:** `%USERPROFILE%\AppData\Local\UnityMCP\UnityMcpServer\src` + - **macOS:** `~/Library/AppSupport/UnityMCP/UnityMcpServer\src` + - **Linux:** `~/.local/share/UnityMCP/UnityMcpServer\src` + - **Verify uv:** Make sure `uv` is installed and working (`uv --version`). + - **Run Manually:** Try running the server directly from the terminal to see errors: + ```bash + cd /path/to/your/UnityMCP/UnityMcpServer/src + uv run server.py + ``` +- **Auto-Configure Failed:** + - Use the Manual Configuration steps. Auto-configure might lack permissions to write to the MCP client's config file. \ No newline at end of file