Content
# Unity MCP Integrated Framework
[](https://opensource.org/licenses/MIT)
An extensible framework for integrating Unity with the Model Context Protocol (MCP). This framework allows AI language models like Claude to interact directly with the Unity editor through a scalable command handler architecture.
## 🌟 Features
- **Extensible Plugin Architecture**: Create and register custom command handlers to extend functionality
- **MCP Integration**: Seamlessly integrate AI models based on the Model Context Protocol
- **TypeScript & C# Support**: Server components are in TypeScript, Unity components are in C#
- **Editor Integration**: Operates as an editor tool with customizable settings
- **Automatic Discovery**: Automatic detection and registration of command handlers
- **Communication**: TCP/IP-based communication between Unity and external AI services
## 📋 Requirements
- Unity 2023.2.19f1 or higher
- .NET/C# 9.0
- Node.js and npm (for TypeScript server)
## 🚀 Getting Started
### Installation
1. Install using the Unity Package Manager:
- Open the Package Manager (Window > Package Manager)
- Click the “+” button
- Select “Add package from git URL...”
- Enter: `https://github.com/isuzu-shiranui/UnityMCP.git?path=jp.shiranui-isuzu.unity-mcp`
### Quick Setup
1. Open Unity and go to Edit > Preferences > Unity MCP
2. Configure connection settings (host and port)
3. Click “Start Server” to begin listening for connections
### Integration with Claude Desktop
1. Download the latest ZIP file from the release page and extract it
2. Note the full path of the `build/index.js` file
3. Open the Claude Desktop configuration file `claude_desktop_config.json`
4. Add the following content and save:
```json
{
"mcpServers": {
"unity-mcp": {
"command": "node",
"args": [
"path/to/index.js"
]
}
}
}
```
* Replace `path/to/index.js` with the actual path (use escaped backslashes for Windows or forward slashes)
## 🔌 Architecture
The Unity MCP framework consists mainly of two components:
### 1. Unity C# Plugin
- **McpServer**: The core server that listens for TCP connections and routes commands
- **IMcpCommandHandler**: An interface for creating custom command handlers
- **McpSettings**: Manages plugin settings
- **McpServiceManager**: A dependency injection system for service management
- **McpHandlerDiscovery**: Automatically detects and registers command handlers
### 2. TypeScript MCP Client
- **HandlerAdapter**: Adapts command handlers to the MCP SDK tools
- **HandlerDiscovery**: Detects and registers command handlers
- **UnityConnection**: Manages TCP/IP communication with Unity
- **BaseCommandHandler**: A base class for implementing command handlers
## 🛠️ Creating Custom Command Handlers
### C# (Unity)
Create a new class that implements `IMcpCommandHandler`:
```csharp
using Newtonsoft.Json.Linq;
using UnityMCP.Editor.Core;
namespace YourNamespace.Handlers
{
internal sealed class YourCommandHandler : IMcpCommandHandler
{
public string CommandPrefix => "yourprefix";
public string Description => "Description of the handler";
public JObject Execute(string action, JObject parameters)
{
// Implement command logic
if (action == "yourAction")
{
// Execute something using parameters
return new JObject
{
["success"] = true,
["result"] = "Result data"
};
}
return new JObject
{
["success"] = false,
["error"] = $"Unknown action: {action}"
};
}
}
}
```
**Note**: Classes implementing `IMcpCommandHandler` can be placed anywhere in the project, and they will be automatically detected and registered through assembly scanning.
### TypeScript (Client)
Extend `BaseCommandHandler` to create a new handler:
```typescript
import { IMcpToolDefinition } from "../core/interfaces/ICommandHandler.js";
import { JObject } from "../types/index.js";
import { z } from "zod";
import { BaseCommandHandler } from "../core/BaseCommandHandler.js";
export class YourCommandHandler extends BaseCommandHandler {
public get commandPrefix(): string {
return "yourprefix";
}
public get description(): string {
return "Description of the handler";
}
protected async executeCommand(action: string, parameters: JObject): Promise<JObject> {
// Implement command logic
// Forward request to Unity
return await this.sendUnityRequest(
`${this.commandPrefix}.${action}`,
parameters
);
}
public getToolDefinitions(): Map<string, IMcpToolDefinition> {
const tools = new Map<string, IMcpToolDefinition>();
// Define tools
tools.set("yourprefix_yourAction", {
description: "Description of the action",
parameterSchema: {
param1: z.string().describe("Description of the parameter"),
param2: z.number().optional().describe("Optional parameter")
}
});
return tools;
}
}
```
### Building and Deploying TypeScript Handlers
Steps to add a custom TypeScript command handler:
1. Create the source code (implement as shown above)
2. Run the build in the TypeScript project:
```bash
npm run build
```
3. Place the built JS file (`YourCommandHandler.js`) in the `build/handlers` directory
4. Restart the server, and the new handler will be automatically detected and registered
This allows anyone to easily add new features without changing the project's source code.
## 🔄 Command Flow
1. Claude (or another AI) calls the MCP tool in TypeScript
2. The TypeScript server forwards the request to Unity via TCP
3. Unity's McpServer receives the request and finds the appropriate handler
4. The handler executes the command on Unity's main thread
5. The result is sent back to the TypeScript server via the TCP connection
6. The TypeScript server formats the result and returns it to Claude
## ⚙️ Configuration
### Unity Settings
Access settings from Edit > Preferences > Unity MCP:
- **Host**: The IP address to bind the server (default: 127.0.0.1)
- **Port**: The port to listen on (default: 27182)
- **Auto-start on Launch**: Automatically start the server when Unity launches
- **Auto-restart on Play Mode Change**: Restart the server on play mode start/stop
- **Detailed Logs**: Enable detailed logs for debugging
### TypeScript Settings
Environment variables for the TypeScript server:
- `UNITY_HOST`: Unity server host (default: 127.0.0.1)
- `UNITY_PORT`: Unity server port (default: 27182)
## 📚 Built-in Command Handlers
### Unity (C#)
- **MenuItemCommandHandler**: Executes menu items in the Unity editor
### TypeScript
- **MenuItemCommandHandler**: Forwards execution of menu items to Unity
## 📄 License
This project is licensed under the MIT License - see the license file for details.
---
Shiranui-Isuzu いすず
