chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,53 @@
|
||||
---
|
||||
id: clients
|
||||
slug: /getting-started/clients
|
||||
title: Choosing an MCP Client
|
||||
sidebar_label: Choosing a Client
|
||||
description: Capability matrix across every MCP client MCP for Unity auto-configures.
|
||||
---
|
||||
|
||||
# Choosing an MCP Client
|
||||
|
||||
MCP for Unity auto-configures every client the package detects on your machine. The differences below decide which one fits your workflow.
|
||||
|
||||
## Capability matrix
|
||||
|
||||
| Client | Transport | Auto-config | Streaming reasoning | Free tier | Notes |
|
||||
|---|---|---|---|---|---|
|
||||
| **Claude Desktop** | stdio only | yes | yes | yes (rate-limited) | Easiest setup. Stdio is silently chosen even if HTTP is selected globally. |
|
||||
| **Claude Code** | HTTP | yes | yes | needs Anthropic plan | First-party. Strong with multi-tool workflows. |
|
||||
| **Cursor** | HTTP | yes | yes | partial | Requires an MCP toggle in Cursor's own settings after auto-config. |
|
||||
| **VS Code (Copilot)** | HTTP | yes | yes | with Copilot | Configures under `servers` (not `mcpServers`). |
|
||||
| **Windsurf** | HTTP | yes | yes | yes | Auto-connects after config. |
|
||||
| **Cline** | HTTP | yes | yes | yes | Auto-connects after config. |
|
||||
| **GitHub Copilot CLI** | HTTP | yes | yes | with Copilot | Terminal-based agent. |
|
||||
| **Codex** | HTTP | yes | yes | with OpenAI | Auto-connects. |
|
||||
| **Qwen Code** | HTTP | yes | yes | yes | Auto-connects. |
|
||||
| **Gemini CLI** | HTTP | yes | yes | yes | Auto-connects. |
|
||||
| **OpenClaw** | HTTP / stdio | yes | yes | yes | Requires `openclaw-mcp-bridge` plugin enabled. Follows MCP for Unity's transport choice. |
|
||||
| **Antigravity** | HTTP | yes | yes | varies | Requires an MCP toggle in Antigravity settings. |
|
||||
|
||||
## How to pick
|
||||
|
||||
- **You want it to just work**: Claude Desktop. Stdio means no port conflicts and no firewall prompts.
|
||||
- **You're building a multi-agent or remote workflow**: anything HTTP. Multiple clients can share one Python server; see [Multi-Instance Routing](/guides/multi-instance).
|
||||
- **You're already in your IDE**: Cursor, VS Code Copilot, or Cline — keeps you in flow.
|
||||
- **You want a terminal**: Claude Code, Copilot CLI, Codex, Gemini CLI, or Qwen Code.
|
||||
|
||||
## Manual configuration
|
||||
|
||||
If auto-config doesn't run (offline machine, sandboxed install, etc.), copy the snippet under **Manual MCP client configuration** in [Install](./install) into your client's MCP config file.
|
||||
|
||||
## Per-client toggle locations
|
||||
|
||||
A few clients need an MCP toggle flipped on after the configurator writes their config. Find it here:
|
||||
|
||||
- **Cursor** → Settings → MCP → enable the `unityMCP` server
|
||||
- **Antigravity** → Settings → MCP servers → enable
|
||||
- **OpenClaw** → enable the `openclaw-mcp-bridge` plugin
|
||||
|
||||
Everything else just connects on next launch.
|
||||
|
||||
## When you update the package
|
||||
|
||||
Run **Window → MCP for Unity → Configure All Detected Clients** any time. It's safe to re-run — the configurator writes idempotently.
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
id: first-prompt
|
||||
slug: /getting-started/first-prompt
|
||||
title: Your First Prompt
|
||||
sidebar_label: Your First Prompt
|
||||
description: End-to-end walkthrough — from typing a prompt to seeing the result in your Unity scene.
|
||||
---
|
||||
|
||||
# Your First Prompt
|
||||
|
||||
You've installed the package and connected a client. Here's what to actually say.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Install](./install) is complete
|
||||
- The MCP for Unity status panel reads `Connected`
|
||||
- Your scene is open in the Unity Editor (any scene will do — even an empty one)
|
||||
|
||||
## The prompt
|
||||
|
||||
In your MCP client (Claude Desktop, Cursor, etc.), say:
|
||||
|
||||
> Create a red, blue, and yellow cube in the current scene, spaced one unit apart on the X axis.
|
||||
|
||||
The assistant should:
|
||||
|
||||
1. Call `manage_scene` (or `find_gameobjects`) to inspect the active scene
|
||||
2. Call `manage_gameobject` three times to create cubes
|
||||
3. Call `manage_material` to create or assign colored materials
|
||||
4. Call `manage_components` to attach the material to each cube's MeshRenderer
|
||||
|
||||
Total round trip is usually 5–15 seconds depending on your network and the client.
|
||||
|
||||
## What you should see in Unity
|
||||
|
||||
Three cubes appear in the **Hierarchy** panel. Switch to the Scene view to see them laid out. If the materials are correct, they'll render red, blue, and yellow.
|
||||
|
||||
If the cubes appear but materials are missing (gray), your project may be using URP/HDRP — the LLM should detect this from `manage_graphics` but sometimes guesses Standard. Tell it explicitly: *"This project uses URP, please use the URP/Lit shader."*
|
||||
|
||||
## Stretching it
|
||||
|
||||
Try escalating prompts in the same session:
|
||||
|
||||
> Add a directional light if there isn't one, and a perspective camera positioned at (0, 2, -5) looking at the cubes.
|
||||
|
||||
> Write a C# script that makes the red cube oscillate up and down by 0.5 units, attach it to the red cube, and enter Play mode.
|
||||
|
||||
> Run all tests in EditMode and report which ones fail.
|
||||
|
||||
Each of these uses a different tool group — `core` for objects/scripts, `core` again for editor mode control, `testing` for test runs (you may need to activate the `testing` group first; see [Tool Groups](/guides/tool-groups)).
|
||||
|
||||
## When something goes wrong
|
||||
|
||||
- **"I couldn't find any Unity instance"** — the server isn't reachable. Check the status panel.
|
||||
- **"Multiple Unity instances detected"** — you have more than one Editor open. See [Multi-Instance Routing](/guides/multi-instance).
|
||||
- **Tool calls succeed but nothing happens in the scene** — your client may be in dry-run mode, or you might have hit an MCP visibility toggle for the relevant tool. Ask the assistant to call `manage_tools` action `list_groups`.
|
||||
|
||||
## What to read next
|
||||
|
||||
- [Choosing an MCP Client](./clients) — capability differences across clients
|
||||
- [Tool Groups](/guides/tool-groups) — enabling vfx, animation, ui, testing, etc.
|
||||
- [Tool reference](/reference/tools) — every available tool with parameters
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
id: index
|
||||
slug: /getting-started
|
||||
title: Overview
|
||||
sidebar_label: Overview
|
||||
description: AI-driven game development for the Unity Editor via the Model Context Protocol.
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
MCP for Unity bridges AI assistants — Claude, Codex, VS Code, local LLMs, and more — with the Unity Editor via the [Model Context Protocol](https://modelcontextprotocol.io/introduction). Give your LLM the tools to manage assets, control scenes, edit scripts, run tests, and automate workflows.
|
||||
|
||||
|
||||
|
||||
## What you get
|
||||
|
||||
- **40+ Unity Editor tools** exposed over MCP — `manage_scene`, `manage_script`, `manage_gameobject`, `manage_material`, `manage_physics`, `run_tests`, and more.
|
||||
- **25+ read-only resources** for state introspection — `editor_state`, `gameobject_components`, `project_info`, `unity_instances`, etc.
|
||||
- **Auto-configuration** for popular MCP clients — Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex, Qwen, Gemini CLI, Copilot CLI, OpenClaw.
|
||||
- **Multi-instance support** — drive several Unity Editors from a single session via `set_active_instance`.
|
||||
- **Two transports** — HTTP (multi-agent, default) and stdio (single-agent legacy).
|
||||
|
||||
## When you'd use it
|
||||
|
||||
- Prototype scenes and gameplay with natural language ("build a player controller with WASD and a double-jump").
|
||||
- Generate and refactor C# scripts with full project context and validation.
|
||||
- Automate repetitive editor tasks — bulk asset processing, scene validation, regression testing.
|
||||
- Build custom AI-driven editor tools on top of the MCP protocol.
|
||||
|
||||
## Next steps
|
||||
|
||||
- **[Install](./install.md)** — Add the Unity package, install the Python server, and connect your first MCP client.
|
||||
- **[Your First Prompt](./first-prompt.md)** — End-to-end "build me a red cube" tutorial.
|
||||
- **[Choosing an MCP Client](./clients.md)** — A capability matrix across all supported clients.
|
||||
- **Setup Wizard** *(coming soon)* — Walk through the first-run experience.
|
||||
|
||||
---
|
||||
|
||||
MIT licensed. Sponsored and maintained by [Aura](https://www.tryaura.dev/). Not affiliated with Unity Technologies.
|
||||
@@ -0,0 +1,139 @@
|
||||
---
|
||||
id: install
|
||||
slug: /getting-started/install
|
||||
title: Install
|
||||
sidebar_label: Install
|
||||
description: Add MCP for Unity to your Unity project and connect an MCP client.
|
||||
---
|
||||
|
||||
# Install
|
||||
|
||||
Three install paths are supported. Pick one. **Git URL** is the fastest if you just want to try it.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Unity 2021.3 LTS or newer** — [Download Unity](https://unity.com/download)
|
||||
- **Python 3.10+** with [`uv`](https://docs.astral.sh/uv/getting-started/installation/) — the setup wizard guides you through both if missing
|
||||
- **An MCP client** — [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://www.cursor.com/), [VS Code Copilot](https://code.visualstudio.com/docs/copilot/overview), [GitHub Copilot CLI](https://docs.github.com/en/copilot/concepts/agents/about-copilot-cli), [Windsurf](https://windsurf.com/), [Cline](https://cline.bot/), [OpenClaw](https://openclaw.ai/), and more
|
||||
|
||||
## Option 1 — Git URL (fastest)
|
||||
|
||||
In Unity, open **Window → Package Manager**, click the **`+`** button, choose **Add package from git URL...**, and paste:
|
||||
|
||||
```text
|
||||
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main
|
||||
```
|
||||
|
||||
For the latest beta features, use the `beta` branch:
|
||||
|
||||
```text
|
||||
https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#beta
|
||||
```
|
||||
|
||||
## Option 2 — Unity Asset Store
|
||||
|
||||
1. Visit [MCP for Unity on the Asset Store](https://assetstore.unity.com/packages/tools/generative-ai/mcp-for-unity-ai-driven-development-329908).
|
||||
2. Click **Add to My Assets**.
|
||||
3. Import via **Window → Package Manager → My Assets**.
|
||||
|
||||
## Option 3 — OpenUPM
|
||||
|
||||
```bash
|
||||
openupm add com.coplaydev.unity-mcp
|
||||
```
|
||||
|
||||
## Start the server and connect
|
||||
|
||||
After import, MCP for Unity opens a **setup wizard** automatically.
|
||||
|
||||
1. Confirm Python and `uv` are installed — the wizard guides you through both if missing.
|
||||
2. Click **Done**. Once dependencies are green, a list of MCP clients detected on your machine appears.
|
||||
3. Pick the clients you want to configure and click **Configure Selected**.
|
||||
|
||||
You can return to this UI anytime via **Window → MCP for Unity** to start/stop the server, switch transport (HTTP vs stdio), or reconfigure clients. The status panel reads `Connected` when everything is wired up.
|
||||
|
||||
### First prompt
|
||||
|
||||
Try one of these in your MCP client:
|
||||
|
||||
> Create a red, blue, and yellow cube in the current scene.
|
||||
|
||||
> Build a simple player controller with WASD movement and a double-jump.
|
||||
|
||||
> List every script in `Assets/Scripts` and tell me which ones reference `Rigidbody`.
|
||||
|
||||
## Per-client notes
|
||||
|
||||
- **Claude Desktop** only supports stdio. MCP for Unity will silently configure it that way even if you have HTTP selected elsewhere.
|
||||
- **Cursor, Antigravity, OpenClaw** still require enabling an MCP toggle or plugin in their own settings after auto-configuration.
|
||||
- **OpenClaw** also needs the `openclaw-mcp-bridge` plugin enabled and follows the currently selected MCP for Unity transport.
|
||||
- **Claude Code, VS Code, Windsurf, Cline, and the CLI clients** auto-connect after configuration.
|
||||
|
||||
Detailed per-client setup lives in the [MCP Client Configurators guide](/guides/client-configurators).
|
||||
|
||||
## Manual MCP client configuration
|
||||
|
||||
If auto-configuration doesn't work for your client, add this to your client's MCP config file:
|
||||
|
||||
### HTTP (default — Cursor, Windsurf, Antigravity, VS Code, Cline, etc.)
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"unityMCP": {
|
||||
"url": "http://localhost:8080/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### VS Code
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"unityMCP": {
|
||||
"type": "http",
|
||||
"url": "http://localhost:8080/mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Stdio (Claude Desktop, or any client without HTTP)
|
||||
|
||||
**macOS / Linux:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"unityMCP": {
|
||||
"command": "uvx",
|
||||
"args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"unityMCP": {
|
||||
"command": "C:/Users/YOUR_USERNAME/AppData/Local/Microsoft/WinGet/Links/uvx.exe",
|
||||
"args": ["--from", "mcpforunityserver", "mcp-for-unity", "--transport", "stdio"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Unity Bridge not connecting** — Open **Window → MCP for Unity** and check the status panel. Restart Unity if needed.
|
||||
- **Server not starting** — Verify `uv --version` works in your terminal. Check the MCP for Unity log for errors.
|
||||
- **Client not connecting** — Confirm the HTTP server is running on `localhost:8080` and the URL in your client config matches.
|
||||
|
||||
For Cursor / VS Code / Windsurf and Claude Code troubleshooting, see the [GitHub Wiki](https://github.com/CoplayDev/unity-mcp/wiki) *(migrating into this site)*.
|
||||
|
||||
Still stuck? [Open an issue](https://github.com/CoplayDev/unity-mcp/issues) or [join Discord](https://discord.gg/y4p8KfzrN4).
|
||||
Reference in New Issue
Block a user