mcp-server.md•6.68 kB
<div align="center">
<h1>Unity MCP server</h1>
[](https://modelcontextprotocol.io/introduction)
[](https://openupm.com/packages/com.ivanmurzak.unity.mcp/)
[](https://hub.docker.com/r/ivanmurzakdev/unity-mcp-server)
[](https://unity.com/releases/editor/archive)
[](https://unity.com/releases/editor/archive)
[](https://github.com/IvanMurzak/Unity-MCP/actions/workflows/release.yml)</br>
[](https://discord.gg/cfbdMZX99G)
[](https://github.com/IvanMurzak/Unity-MCP/stargazers)
[](https://github.com/IvanMurzak/Unity-MCP/blob/main/LICENSE)
[](https://stand-with-ukraine.pp.ua)
Model Context Protocol implementation for Unity Editor and for games made with Unity.
</div>
## Topology
- **Client** is the MCP client, such as VS Code, Cursor, Claude Desktop, Claude Code etc.
- **Server** is the MCP server, this is Unity-MCP server implementation which works closely in pair with Unity MCP Plugin
- **Plugin** is the Unity-MCP Plugin, this is deeply connected with Unity Editor and runtime game build SDK, that exposes API for the Server and lets the AI magic to happen. It utilizes advanced reflection by using [ReflectorNet](https://github.com/IvanMurzak/ReflectorNet)
### Connection chain
**Client** <-> **Server** <-> **Plugin** (Unity Editor / Game Build)
---
### Variables
Doesn't matter what launch option you choose, all of them support custom configuration using both Environment Variables and Command Line Arguments. It would work with default values, if you just need to launch it, don't waste your time for the variables. Just make sure Unity Plugin also has default values, especially the `--port`, they should be equal.
| Environment Variable | Command Line Args | Description |
|-----------------------------|-----------------------|-----------------------------------------------------------------------------|
| `UNITY_MCP_PORT` | `--port` | **Client** -> **Server** <- **Plugin** connection port (default: 8080) |
| `UNITY_MCP_PLUGIN_TIMEOUT` | `--plugin-timeout` | **Plugin** -> **Server** connection timeout (ms) (default: 10000) |
| `UNITY_MCP_CLIENT_TRANSPORT`| `--client-transport` | **Client** -> **Server** transport type: `stdio` or `http` (default: `http`) |
---
## Launch
Unity-MCP server is developed with idea of flexibility in mind, that is why it has many launch options.
### Option: Using Docker (recommended)
#### Default launch
The default the transport method is `http`. The port `8080` should be forwarded. It will be used for http transport and for **plugin** <-> **server** communication
```bash
docker run -p 8080:8080 ivanmurzakdev/unity-mcp-server
```
MCP client config:
```json
{
"mcpServers": {
"Unity-MCP": {
"url": "http://localhost:8080"
}
}
}
```
#### Use STDIO
The `8080` port is not needed for STDIO, because it uses the STDIO to communicate with **Client**. It is a good setup for using in a client with automatic installation and launching. Because this docker command loads the image from docker hub and launches immediately.
```bash
docker run -t -e UNITY_MCP_CLIENT_TRANSPORT=stdio -p 8080:8080 ivanmurzakdev/unity-mcp-server
```
MCP client config:
```json
{
"mcpServers": {
"Unity-MCP": {
"command": "docker",
"args": [
"run",
"-t",
"-e",
"UNITY_MCP_CLIENT_TRANSPORT=stdio",
"-p",
"8080:8080",
"ivanmurzakdev/unity-mcp-server"
]
}
}
}
```
#### Custom port
```bash
docker run -e UNITY_MCP_PORT=123 -p 123:123 ivanmurzakdev/unity-mcp-server
```
MCP client config:
```json
{
"mcpServers": {
"Unity-MCP": {
"url": "http://localhost:123"
}
}
}
```
Port forwarding is need for the launch with docker `-p 123:123`.
---
### Option: Using binary file
Download binary from the [GitHub releases page](https://github.com/IvanMurzak/Unity-MCP/releases). Unpack the zip archive and use command line to simply launch binary of the server for your target operation system and CPU architecture.
#### Default launch (STDIO)
```bash
./unity-mcp-server --client-transport stdio
```
MCP client config:
> Replace `<project>` with your Unity project path.
```json
{
"mcpServers": {
"Unity-MCP": {
"command": "<project>/Library/mcp-server/win-x64/unity-mcp-server.exe",
"args": [
"--client-transport=stdio"
]
}
}
}
```
#### Launch STDIO (Local)
Launch server with STDIO transport type for local usage on the same machine with Unity Editor.
```bash
./unity-mcp-server --port 8080 --plugin-timeout 10000 --client-transport stdio
```
MCP client config:
> Replace `<project>` with your Unity project path.
```json
{
"mcpServers": {
"Unity-MCP": {
"command": "<project>/Library/mcp-server/win-x64/unity-mcp-server.exe",
"args": [
"--port=8080",
"--plugin-timeout=10000",
"--client-transport=stdio"
]
}
}
}
```
#### Launch HTTP(S) (Local OR Remote)
Launch server with HTTP transport type for local OR remote usage using HTTP(S) url.
```bash
./unity-mcp-server --port 8080 --plugin-timeout 10000 --client-transport http
```
MCP client config:
> Replace `<project>` with your Unity project path.
```json
{
"mcpServers": {
"Unity-MCP": {
"command": "<project>/Library/mcp-server/win-x64/unity-mcp-server.exe",
"args": [
"--port=8080",
"--plugin-timeout=10000",
"--client-transport=http"
]
}
}
}
```
---