Content
# Unity MCP Integration Framework
[](https://opensource.org/licenses/MIT)
[English Version](./README.en.md)
An extensible framework for integrating Unity with the Model Context Protocol (MCP). This framework allows AI language models such as Claude to interact directly with the Unity editor through a scalable handler architecture.
## 🌟 Features
- **Extensible Plugin Architecture**: Create and register custom handlers to extend functionality
- **Complete MCP Integration**: Supports all MCP basic functions for commands, resources, and prompts
- **TypeScript & C# Support**: Server components are TypeScript, Unity components are C#
- **Editor Integration**: Operates as an editor tool with customizable settings
- **Auto-Detection**: Automatic detection and registration of various handlers
- **Communication**: TCP/IP-based communication between Unity and external AI services
## 📋 Requirements
- Unity 2022.3.22f1 or higher (also compatible with Unity 6.1)
- Verified to work with 2022.3.22f1, 2023.2.19f1, 6000.0.35f1, 6000.1.0f1
- .NET/C# 9.0
- Node.js 18.0.0 or higher and npm (for TypeScript server)
- Please install from the [Node.js official website](https://nodejs.org/)
## 🚀 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 navigate to Edit > Preferences > Unity MCP
2. Configure the connection settings (host and port)
3. Click the "Connect" button to start listening for connections
### Integration with Claude Desktop
#### Using the Installer
Unity MCP includes a tool for easy installation and configuration of the TypeScript client.
1. In the Unity editor, go to "Edit > Preferences > Unity MCP"
2. Click the "Open Installer Window" button to open the TypeScript client installer
3. Follow the instructions in the installer:
- Make sure Node.js is installed (if not, a download link will be displayed)
- Click the "Latest" button to get the latest version
- Select the installation folder and click the "Download and Install TypeScript Client" button
- Once the installation is complete, open the "Configuration Preview" section and copy the configuration JSON to the clipboard
4. Configure Claude Desktop:
- Open Claude Desktop
- Click the "Claude" menu and select "Settings..."
- Click the "Developer" tab and click the "Edit Config" button
- Paste the copied configuration and save
5. Restart Claude Desktop to apply the settings
Now, Claude Desktop will automatically connect to the Unity MCP client, enabling seamless integration with the Unity Editor.
#### Manual Installation
1. Download the latest ZIP file from the release page and extract it
2. Note the full path to 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 (escape backslashes "\\\\" or use forward slashes "/" in Windows)
## 🔌 Architecture
The Unity MCP framework mainly consists of two components:
### 1. Unity C# Plugin
- **McpServer**: Core server that listens for TCP connections and routes commands
- **IMcpCommandHandler**: Interface for creating custom command handlers
- **IMcpResourceHandler**: Interface for creating data providing resources
- **McpSettings**: Manages plugin settings
- **McpServiceManager**: Dependency injection system for service management
- **McpHandlerDiscovery**: Automatically detects and registers various handlers
### 2. TypeScript MCP Client
- **HandlerAdapter**: Adapts various handlers to the MCP SDK
- **HandlerDiscovery**: Detects and registers handler implementations
- **UnityConnection**: Manages TCP/IP communication with Unity
- **BaseCommandHandler**: Base class for command handler implementations
- **BaseResourceHandler**: Base class for resource handler implementations
- **BasePromptHandler**: Base class for prompt handler implementations
## 📄 MCP Handler Types
Unity MCP supports the following three types of handlers based on the Model Context Protocol (MCP):
### 1. Command Handlers (Tools)
- **Purpose**: Tools for performing actions (making Unity execute something)
- **Control**: Model-controlled - AI model can call automatically
- **Implementation**: Implement the IMcpCommandHandler interface
### 2. Resource Handlers (Resources)
- **Purpose**: Resources for accessing data within Unity (providing information)
- **Control**: Application-controlled - Client application decides when to use
- **Implementation**: Implement the IMcpResourceHandler interface
### 3. Prompt Handlers (Prompts)
- **Purpose**: Reusable prompt templates and workflows
- **Control**: User-controlled - User explicitly selects and uses
- **Implementation**: Implement the IPromptHandler interface (TypeScript side only)
## 🔬 Sample Code
The package includes the following samples:
1. **Unity MCP Handler Samples**
- Sample code for C# implementation
- Can be imported directly into the project and used
2. **Unity MCP Handler Samples JavaScript**
- Sample code for JavaScript implementation
- Copy the JS files in this to the `build/handlers` directory and use
> ⚠️ **Caution**: The sample code includes arbitrary code execution functionality. Use caution when using in a production environment.
How to import samples:
1. Select this package in the Unity Package Manager
2. Click the "Samples" tab
3. Click the "Import" button for the required sample
## 🛠️ Creating Custom Handlers
### Command Handler (C#)
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 => "ハンドラーの説明";
public JObject Execute(string action, JObject parameters)
{
// コマンドロジックを実装
if (action == "yourAction")
{
// パラメータを使って何かを実行
return new JObject
{
["success"] = true,
["result"] = "結果データ"
};
}
return new JObject
{
["success"] = false,
["error"] = $"不明なアクション: {action}"
};
}
}
}
```
### Resource Handler (C#)
Create a new class that implements `IMcpResourceHandler`:
```csharp
using Newtonsoft.Json.Linq;
using UnityMCP.Editor.Resources;
namespace YourNamespace.Resources
{
internal sealed class YourResourceHandler : IMcpResourceHandler
{
public string ResourceName => "yourresource";
public string Description => "リソースの説明";
public string ResourceUri => "unity://yourresource";
public JObject FetchResource(JObject parameters)
{
// リソースデータを取得する処理を実装
var data = new JArray();
// 何かデータを取得・加工してJArrayに追加
data.Add(new JObject
{
["name"] = "項目1",
["value"] = "値1"
});
return new JObject
{
["success"] = true,
["items"] = data
};
}
}
}
```
### Command Handler (TypeScript)
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 "ハンドラーの説明";
}
public getToolDefinitions(): Map<string, IMcpToolDefinition> {
const tools = new Map<string, IMcpToolDefinition>();
// ツールを定義
tools.set("yourprefix_yourAction", {
description: "アクションの説明",
parameterSchema: {
param1: z.string().describe("パラメータの説明"),
param2: z.number().optional().describe("オプションパラメータ")
},
annotations: {
title: "ツールのタイトル",
readOnlyHint: true,
openWorldHint: false
}
});
return tools;
}
protected async executeCommand(action: string, parameters: JObject): Promise<JObject> {
// コマンドロジックを実装
// リクエストを Unity に転送
return await this.sendUnityRequest(
`${this.commandPrefix}.${action}`,
parameters
);
}
}
```
### Resource Handler (TypeScript)
Extend `BaseResourceHandler` to create a new resource handler:
```typescript
import { BaseResourceHandler } from "../core/BaseResourceHandler.js";
import { JObject } from "../types/index.js";
import { URL } from "url";
export class YourResourceHandler extends BaseResourceHandler {
public get resourceName(): string {
return "yourresource";
}
public get description(): string {
return "リソースの説明";
}
public get resourceUriTemplate(): string {
return "unity://yourresource";
}
protected async fetchResourceData(uri: URL, parameters?: JObject): Promise<JObject> {
// リクエストパラメータを処理
const param1 = parameters?.param1 as string;
// Unityにリクエストを送信
const response = await this.sendUnityRequest("yourresource.get", {
param1: param1
});
if (!response.success) {
throw new Error(response.error as string || "リソース取得に失敗しました");
}
// 応答データを整形して返す
return {
items: response.items || []
};
}
}
```
### Prompt Handler (TypeScript)
Extend `BasePromptHandler` to create a new prompt handler:
```typescript
import { BasePromptHandler } from "../core/BasePromptHandler.js";
import { IMcpPromptDefinition } from "../core/interfaces/IPromptHandler.js";
import { z } from "zod";
export class YourPromptHandler extends BasePromptHandler {
public get promptName(): string {
return "yourprompt";
}
public get description(): string {
return "プロンプトの説明";
}
public getPromptDefinitions(): Map<string, IMcpPromptDefinition> {
const prompts = new Map<string, IMcpPromptDefinition>();
// プロンプト定義を登録
prompts.set("analyze-component", {
description: "Unityコンポーネントを分析する",
template: "以下のUnityコンポーネントを詳細に分析し、改善点を提案してください:\n\n```csharp\n{code}\n```",
additionalProperties: {
code: z.string().describe("分析対象のC#コード")
}
});
return prompts;
}
}
```
**Note**: Classes implementing `IMcpCommandHandler` or `IMcpResourceHandler` on the C# side are automatically detected and registered by assembly search, regardless of their location within the project. Similarly, TypeScript side are automatically detected by placing them in the `handlers` directory.
## 🔄 Communication Flow
1. Claude (or another AI) calls one of MCP's functions (tool/resource/prompt)
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 processes the request in Unity's main thread
5. The result is returned to the TypeScript server via the TCP connection
6. The TypeScript server formats the result and returns it to Claude
## ⚙️ Configuration
### Unity Configuration
Access the settings from Edit > Preferences > Unity MCP:
- **Host**: IP address to bind the server to (default: 127.0.0.1)
- **Port**: Port to listen on (default: 27182)
- **UDP Discovery**: Enable automatic discovery of the TypeScript server
- **Auto-start on Launch**: Automatically start the server when Unity launches
- **Auto-restart on Play Mode Change**: Restart the server when entering/exiting play mode
- **Detailed Logs**: Enable detailed logs for debugging
### TypeScript Configuration
Environment variables for the TypeScript server:
- `MCP_HOST`: Unity server host (default: 127.0.0.1)
- `MCP_PORT`: Unity server port (default: 27182)
## 🔍 Troubleshooting
### Common Issues
1. **Connection Error**
- Check the firewall settings on the Unity side
- Check that the port number is configured correctly
- Check that another process is not using the same port
2. **Handler Not Registered**
- Check that the handler class implements the correct interface
- Check that the C# handler has public or internal access level
- Check the logs on the Unity side to see if an error occurred during the registration process
3. **Resource Not Found**
- Check that the resource name and URI match
- Check that the resource handler is correctly enabled
### Checking Logs
- Unity Console: Check log messages from McpServer
- TypeScript server: Check the console output for communication errors using MCP Inspector, etc.
## 📚 Built-in Handlers
### Unity (C#)
- **MenuItemCommandHandler**: Execute Unity editor menu items
- **ConsoleCommandHandler**: Unity console log operations
- **AssembliesResourceHandler**: Get assembly information
- **PackagesResourceHandler**: Get package information
### TypeScript
- **MenuItemCommandHandler**: Execute menu items
- **ConsoleCommandHandler**: Console log operations
- **AssemblyResourceHandler**: Get assembly information
- **PackageResourceHandler**: Get package information
## 📖 External Resources
- [Model Context Protocol (MCP) Specification](https://modelcontextprotocol.io/introduction)
## ⚠️ Security Considerations
1. **Do not execute untrusted handlers**: Before using handler code created by a third party, perform a security review.
2. **Limit code execution privileges**: Handlers that include the `code_execute` command in particular can execute arbitrary code, so consider disabling them in production environments.
## 📄 License
This project is provided under the MIT License - see the license file for details.
---
Shiranui-Isuzu いすず
