{"id":26718556,"url":"https://github.com/justinpbarnett/unity-mcp","last_synced_at":"2025-05-14T18:02:39.316Z","repository":{"id":283066874,"uuid":"950564038","full_name":"justinpbarnett/unity-mcp","owner":"justinpbarnett","description":"A Unity MCP server that allows MCP clients like Claude Desktop or Cursor to perform Unity Editor actions.","archived":false,"fork":false,"pushed_at":"2025-04-09T13:19:24.000Z","size":270,"stargazers_count":1971,"open_issues_count":52,"forks_count":276,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-05-14T18:02:35.465Z","etag":null,"topics":["ai","ai-integration","mcp","unity"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/justinpbarnett.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"justinpbarnett","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-03-18T11:01:58.000Z","updated_at":"2025-05-14T16:48:21.000Z","dependencies_parsed_at":"2025-04-03T18:11:03.544Z","dependency_job_id":"02fea1ab-ef6b-4217-b05f-e19972c6ceca","html_url":"https://github.com/justinpbarnett/unity-mcp","commit_stats":null,"previous_names":["justinpbarnett/unity-mcp"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinpbarnett%2Funity-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinpbarnett%2Funity-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinpbarnett%2Funity-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justinpbarnett%2Funity-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justinpbarnett","download_url":"https://codeload.github.com/justinpbarnett/unity-mcp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198452,"owners_count":22030964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-integration","mcp","unity"],"created_at":"2025-03-27T17:35:00.268Z","updated_at":"2025-05-14T18:02:39.281Z","avatar_url":"https://github.com/justinpbarnett.png","language":"C#","funding_links":["https://github.com/sponsors/justinpbarnett"],"categories":["🤖 AI/ML","Servers","Mcp Servers","Gaming and Game Development","MCP Clients"],"sub_categories":["DotNET","integration","Domain-Specific Integrations"],"readme":"# Unity MCP ✨\n\n**Connect your Unity Editor to LLMs using the Model Context Protocol.**\n\nUnity MCP acts as a bridge, allowing AI assistants (like Claude, Cursor) to interact directly with your Unity Editor via a local **MCP (Model Context Protocol) Client**. Give your LLM tools to manage assets, control scenes, edit scripts, and automate tasks within Unity.\n\n---\n\n## \u003cpicture\u003e\u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/justinpbarnett/unity-mcp/assets/11047284/c279675a-dd58-406b-9613-5b16b5c6bb63\"\u003e\u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/justinpbarnett/unity-mcp/assets/11047284/b54f891d-961b-4048-a9c4-3af46e2a52fc\"\u003e\u003cimg alt=\"UnityMCP Workflow\" width=\"100%\" style=\"max-width: 600px; display: block; margin-left: auto; margin-right: auto;\"\u003e\u003c/picture\u003e\n\n## Key Features 🚀\n\n*   **🗣️ Natural Language Control:** Instruct your LLM to perform Unity tasks.\n*   **🛠️ Powerful Tools:** Manage assets, scenes, materials, scripts, and editor functions.\n*   **🤖 Automation:** Automate repetitive Unity workflows.\n*   **🧩 Extensible:** Designed to work with various MCP Clients.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eExpand for Available Tools...\u003c/strong\u003e\u003c/summary\u003e\n\n  Your LLM can use functions like:\n\n  *   `read_console`: Gets messages from or clears the console.\n  *   `manage_script`: Manages C# scripts (create, read, update, delete).\n  *   `manage_editor`: Controls and queries the editor's state and settings.\n  *   `manage_scene`: Manages scenes (load, save, create, get hierarchy, etc.).\n  *   `manage_asset`: Performs asset operations (import, create, modify, delete, etc.).\n  *   `manage_gameobject`: Manages GameObjects: create, modify, delete, find, and component operations.\n  *   `execute_menu_item`: Executes a menu item via its path (e.g., \"File/Save Project\").\n\u003c/details\u003e\n\n---\n\n## How It Works 🤔\n\nUnity MCP connects your tools using two components:\n\n1.  **Unity MCP Bridge:** A Unity package running inside the Editor. (Installed via Package Manager).\n2.  **Unity MCP Server:** A Python server that runs locally, communicating between the Unity Bridge and your MCP Client. (Installed manually).\n\n**Flow:** `[Your LLM via MCP Client] \u003c-\u003e [Unity MCP Server (Python)] \u003c-\u003e [Unity MCP Bridge (Unity Editor)]`\n\n---\n\n## Installation ⚙️\n\n\u003e **Note:** The setup is constantly improving as we update the package. Check back if you randomly start to run into issues.\n\n### Prerequisites\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eClick to view required software...\u003c/strong\u003e\u003c/summary\u003e\n\n  *   **Git CLI:** For cloning the server code. [Download Git](https://git-scm.com/downloads)\n  *   **Python:** Version 3.12 or newer. [Download Python](https://www.python.org/downloads/)\n  *   **Unity Hub \u0026 Editor:** Version 2020.3 LTS or newer. [Download Unity](https://unity.com/download)\n  *   **uv (Python package manager):**\n      ```bash\n      pip install uv\n      # Or see: https://docs.astral.sh/uv/getting-started/installation/\n      ```\n  *   **An MCP Client:**\n      *   [Claude Desktop](https://claude.ai/download)\n      *   [Cursor](https://www.cursor.com/en/downloads)\n      *   *(Others may work with manual config)*\n\u003c/details\u003e\n\n### Step 1: Install the Unity Package (Bridge)\n\n1.  Open your Unity project.\n2.  Go to `Window \u003e Package Manager`.\n3.  Click `+` -\u003e `Add package from git URL...`.\n4.  Enter:\n    ```\n    https://github.com/justinpbarnett/unity-mcp.git?path=/UnityMcpBridge\n    ```\n5.  Click `Add`.\n6. The MCP Server should automatically be installed onto your machine as a result of this process.\n\n### Step 2: Configure Your MCP Client\n\nConnect your MCP Client (Claude, Cursor, etc.) to the Python server you installed in Step 1.\n\n**Option A: Auto-Configure (Recommended for Claude/Cursor)**\n\n1.  In Unity, go to `Window \u003e Unity MCP`.\n2.  Click `Auto Configure Claude` or `Auto Configure Cursor`.\n3.  Look for a green status indicator 🟢 and \"Connected\". *(This attempts to modify the MCP Client's config file automatically)*.\n\n**Option B: Manual Configuration**\n\nIf Auto-Configure fails or you use a different client:\n\n1.  **Find your MCP Client's configuration file.** (Check client documentation).\n    *   *Claude Example (macOS):* `~/Library/Application Support/Claude/claude_desktop_config.json`\n    *   *Claude Example (Windows):* `%APPDATA%\\Claude\\claude_desktop_config.json`\n2.  **Edit the file** to add/update the `mcpServers` section, using the *exact* paths from Step 1.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eClick for OS-Specific JSON Configuration Snippets...\u003c/strong\u003e\u003c/summary\u003e\n\n**Windows:**\n\n  ```json\n  {\n    \"mcpServers\": {\n      \"UnityMCP\": {\n        \"command\": \"uv\",\n        \"args\": [\n          \"run\",\n          \"--directory\",\n          \"C:\\\\Users\\\\YOUR_USERNAME\\\\AppData\\\\Local\\\\Programs\\\\UnityMCP\\\\UnityMcpServer\\\\src\",\n          \"server.py\"\n        ]\n      }\n      // ... other servers might be here ...\n    }\n  }\n``` \n\n(Remember to replace YOUR_USERNAME and use double backslashes \\\\)\n\n**macOS:**\n\n```json\n{\n  \"mcpServers\": {\n    \"UnityMCP\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--directory\",\n        \"/usr/local/bin/UnityMCP/UnityMcpServer/src\",\n        \"server.py\"\n      ]\n    }\n    // ... other servers might be here ...\n  }\n}\n```\n(Replace YOUR_USERNAME if using ~/bin)\n\n**Linux:**\n\n```json\n{\n  \"mcpServers\": {\n    \"UnityMCP\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--directory\",\n        \"/home/YOUR_USERNAME/bin/UnityMCP/UnityMcpServer/src\",\n        \"server.py\"\n      ]\n    }\n    // ... other servers might be here ...\n  }\n}\n```\n\n(Replace YOUR_USERNAME)\n\n\u003c/details\u003e\n\n---\n\n## Usage ▶️\n\n1. **Open your Unity Project.** The Unity MCP Bridge (package) should connect automatically. Check status via Window \u003e Unity MCP.\n    \n2. **Start your MCP Client** (Claude, Cursor, etc.). It should automatically launch the Unity MCP Server (Python) using the configuration from Installation Step 3.\n    \n3. **Interact!** Unity tools should now be available in your MCP Client.\n    \n    Example Prompt: `Create a 3D player controller.`\n    \n\n---\n\n## Contributing 🤝\n\nHelp make Unity MCP better!\n\n1. **Fork** the main repository.\n    \n2. **Create a branch** (`feature/your-idea` or `bugfix/your-fix`).\n    \n3. **Make changes.**\n    \n4. **Commit** (feat: Add cool new feature).\n    \n5. **Push** your branch.\n    \n6. **Open a Pull Request** against the master branch.\n    \n\n---\n\n## Troubleshooting ❓\n\n\u003cdetails\u003e  \n\u003csummary\u003e\u003cstrong\u003eClick to view common issues and fixes...\u003c/strong\u003e\u003c/summary\u003e  \n\n- **Unity Bridge Not Running/Connecting:**\n    \n    - Ensure Unity Editor is open.\n        \n    - Check the status window: Window \u003e Unity MCP.\n        \n    - Restart Unity.\n        \n- **MCP Client Not Connecting / Server Not Starting:**\n    \n    - **Verify Server Path:** Double-check the --directory path in your MCP Client's JSON config. It must exactly match the location where you cloned the UnityMCP repository in Installation Step 1 (e.g., .../Programs/UnityMCP/UnityMcpServer/src).\n        \n    - **Verify uv:** Make sure uv is installed and working (pip show uv).\n        \n    - **Run Manually:** Try running the server directly from the terminal to see errors: `# Navigate to the src directory first! cd /path/to/your/UnityMCP/UnityMcpServer/src uv run server.py`\n        \n    - **Permissions (macOS/Linux):** If you installed the server in a system location like /usr/local/bin, ensure the user running the MCP client has permission to execute uv and access files there. Installing in ~/bin might be easier.\n        \n- **Auto-Configure Failed:**\n    \n    - Use the Manual Configuration steps. Auto-configure might lack permissions to write to the MCP client's config file.\n        \n\n\u003c/details\u003e  \n\nStill stuck? [Open an Issue](https://www.google.com/url?sa=E\u0026q=https%3A%2F%2Fgithub.com%2Fjustinpbarnett%2Funity-mcp%2Fissues).\n\n---\n\n## License 📜\n\nMIT License. See [LICENSE](https://www.google.com/url?sa=E\u0026q=https%3A%2F%2Fgithub.com%2Fjustinpbarnett%2Funity-mcp%2Fblob%2Fmaster%2FLICENSE) file.\n\n---\n\n## Contact 👋\n\n- **X/Twitter:** [@justinpbarnett](https://www.google.com/url?sa=E\u0026q=https%3A%2F%2Fx.com%2Fjustinpbarnett)\n    \n\n---\n\n## Acknowledgments 🙏\n\nThanks to the contributors and the Unity team.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinpbarnett%2Funity-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustinpbarnett%2Funity-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustinpbarnett%2Funity-mcp/lists"}