モデルコンテキストプロトコル (MCP) を使用した Unity と AI アシスタント間のブリッジ。
Unity-MCPは、Unityゲーム開発向けのモデルコンテキストプロトコル（Model Context Protocol）のオープンソース実装です。AIアシスタントが標準化されたインターフェースを介してUnityゲーム環境と対話できるようにすることで、AIを活用したゲーム開発、自動テスト、シーン分析、ランタイムデバッグが可能になります。
永続性のために AILogger を使用するようにアーキテクチャが簡素化され、別個のサーバー コンポーネントが不要になりました。
AI Assistant <-> Unity-MCP STDIO Client <-> Unity Client <-> AILoggerAIアシスタント:MCPプロトコルを使用してUnity-MCP STDIOクライアントと通信します。
Unity-MCP STDIOクライアント: コマンドをUnityクライアントに転送し、結果をAILoggerに保存します。
Unityクライアント: Unityでコマンドを実行し、結果を返します
AILogger : ログと結果を後から取得できるように保存します
Unity-MCP STDIOクライアントは、コード実行とクエリの両方のエンドポイントを提供するUnityクライアントと直接通信します。クエリツールは、クエリをreturn文でラップすることで、コード実行に変換します。
Related MCP server: Advanced Unity MCP
Unity ランタイム環境で C# コードを実行する
ゲームオブジェクトとそのコンポーネントを検査する
シーンの階層と構造を分析する
テストを実行して結果を受け取る
ゲームオブジェクトとコンポーネントのメソッドを呼び出す
実行中にゲームの状態を変更する
Unity エディター拡張機能: ゲーム実行サイクルを超えて存続するエディター拡張機能
Dockerコンテナ: ネットワーク経由でUnityと通信するコンテナ化されたバージョン
NPX パッケージ: NPX 経由でインストールおよび実行できる Node.js パッケージ
MCP アーキテクチャ: MCP アーキテクチャと名前空間の概要
MCP STDIO クライアント: MCP STDIO クライアントとそのログ機能に関する情報
クエリツール: クエリツールとその仕組みに関する詳細情報
AILogger 統合: AILogger 統合の詳細情報
APIリファレンス: APIエンドポイントの詳細情報
インストールガイド: Unity-MCP のインストールと設定の手順
開発ガイド: 開発環境とワークフローに関する情報
ホットリロードガイド:開発環境でのホットリロードに関する詳細情報
ホットリロードクイックリファレンス：ホットリロードコマンドとヒントのクイックリファレンスガイド
貢献ガイド: プロジェクトへの貢献に関するガイドライン
Unity-MCP を使い始めるには、次の手順に従います。
リポジトリをクローンします。
git clone https://github.com/TSavo/Unity-MCP.git
cd Unity-MCP依存関係をインストールします:
npm installプロジェクトをビルドします。
npm run buildMCP STDIO クライアントを起動します。
npm startこれにより、Unity と通信し、永続性のために AILogger を使用する MCP STDIO クライアントが起動します。
注意: AILogger がhttp://localhost:3030で実行されていることを確認するか、AI_LOGGER_URL 環境変数を AILogger インスタンスを指すように設定してください。
テストを実行します:
# Run all tests
npm test
# Run only unit tests
npm run test:unit
# Run only e2e tests
npm run test:e2e
# Run tests with a specific pattern
npm test -- --testNamePattern="should return the server manifest"
npm run test:unit -- --testNamePattern="should return the server manifest"
npm run test:e2e -- --testNamePattern="should discover the test server"詳細な手順については、インストール ガイドを参照してください。
Unity-MCP ブリッジを AI アシスタントに接続するには、MCP 構成ファイルを作成する必要があります。
{
"mcpServers": {
"unity-ai-bridge": {
"url": "http://localhost:8080/sse"
}
}
}このファイルをAIアシスタントの適切な場所に配置してください。Claudeの場合、通常はClaudeデスクトップアプリの設定ディレクトリ内にあります。
Unity-MCP ブリッジは次のツールを提供します。
execute_code : Unity で C# コードを直接実行します。
query : ドット表記を使用してクエリを実行し、オブジェクト、プロパティ、メソッドにアクセスします。
get_logs : AILogger からログを取得します。
get_log_by_name : AILogger から特定のログを取得します。
execute_codeツールを使用して、Unity で C# コードを実行できます。コードは Unity ランタイム環境で実行され、結果は AILogger に保存され、後で取得できます。
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "execute_code",
"arguments": {
"code": "Debug.Log(\"Hello from Unity!\"); return GameObject.FindObjectsOfType<GameObject>().Length;",
"timeout": 5000
}
}
}{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"success\",\"logName\":\"unity-execute-1712534400000\",\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123}}"
}
]
}
}queryツールを使用してUnityオブジェクトをクエリできます。これにより、ドット表記を使用してオブジェクト、プロパティ、メソッドにアクセスできます。
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "query",
"arguments": {
"query": "Camera.main.transform.position",
"timeout": 5000
}
}
}{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"success\",\"logName\":\"unity-query-1712534400000\",\"result\":{\"success\":true,\"result\":{\"x\":0,\"y\":1,\"z\":-10},\"executionTime\":45}}"
}
]
}
}get_log_by_nameツールを使用して、AILogger から以前の操作の結果を取得できます。
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "get_log_by_name",
"arguments": {
"log_name": "unity-execute-1712534400000",
"limit": 1
}
}
}{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [
{
"type": "text",
"text": "{\"status\":\"success\",\"name\":\"unity-execute-1712534400000\",\"entries\":[{\"id\":\"123e4567-e89b-12d3-a456-426614174000\",\"name\":\"unity-execute-1712534400000\",\"data\":{\"result\":{\"success\":true,\"result\":42,\"logs\":[\"Hello from Unity!\"],\"executionTime\":123},\"timestamp\":\"2025-04-08T00:00:00.000Z\"},\"timestamp\":\"2025-04-08T00:00:00.000Z\"}]}"
}
]
}
}AI アシスタントが Unity ツールにアクセスできるようになると、次のようなタスクを実行するように依頼できます。
Can you execute the following C# code in Unity?
GameObject.Find("Player").transform.position = new Vector3(0, 1, 0);マサチューセッツ工科大学
Tサボ（ @TSavo ）
Lists all the files inside a Unity project.
| Name | Required | Description | Default |
|---|---|---|---|
| projectName | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Lists') but doesn't describe key traits like whether it's read-only (implied but not explicit), what format the output takes (e.g., list of filenames vs. metadata), pagination, error conditions, or permissions required. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It's appropriately sized for a simple listing tool and front-loaded with the core action, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is incomplete. It lacks details on parameter semantics, output format, and behavioral context (e.g., read-only nature, error handling). While concise, it doesn't provide enough information for an agent to use the tool effectively without additional assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the parameter 'projectName' is undocumented in the schema. The description adds no information about this parameter—it doesn't explain what 'projectName' refers to (e.g., a Unity project identifier), valid formats, or examples. With low schema coverage, the description fails to compensate, leaving the parameter's meaning unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Lists') and resource ('all the files inside a Unity project'), making the tool's purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_projects' (which lists projects) or 'read_file' (which reads file contents), missing the opportunity to clarify its specific scope within the toolset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing project), exclusions, or comparisons to siblings like 'list_projects' for project-level listing or 'read_file' for accessing file details. This leaves the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all available Unity projects.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits like whether results are paginated, sorted, filtered, or include metadata; whether it requires authentication; or what the return format looks like. This leaves significant gaps for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose with zero wasted words. It's appropriately sized for a simple list operation with no parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'lists' entails (e.g., format, metadata included) or behavioral aspects, leaving the agent with insufficient context to understand the tool's full behavior beyond its basic purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't mention parameters, earning a baseline high score since it doesn't need to compensate for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Lists') and resource ('all available Unity projects'), making the purpose immediately understandable. It doesn't differentiate from sibling tools like 'list_files_in_project' or 'read_file', which would require mentioning it returns project-level metadata rather than file contents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that 'list_files_in_project' is for files within a specific project or 'read_file' is for file contents, leaving the agent to infer usage from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the contents of a file inside a Unity project.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Reads') but doesn't mention potential constraints like file size limits, encoding issues, error handling for missing files, or performance implications. This leaves significant gaps in understanding how the tool behaves beyond its basic function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It front-loads the core action and context efficiently, making it easy to parse and understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (reading file contents), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., text content, binary data, error messages) or address common edge cases like permissions or file existence, making it inadequate for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It implies the 'path' parameter refers to a file path within a Unity project, adding context beyond the schema's minimal type constraints. However, it doesn't specify path format (e.g., relative vs. absolute), supported file types, or examples, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reads') and target ('contents of a file inside a Unity project'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'list_files_in_project' (which enumerates files vs. reading content), leaving room for minor ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'list_files_in_project' or 'list_projects'. It mentions the context ('inside a Unity project') but lacks explicit when-to-use or when-not-to-use instructions, leaving the agent to infer usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0list_files_in_projectlist_projectsread_fileScored across 3 tools
Each tool has a clearly distinct purpose: list_projects enumerates projects, list_files_in_project enumerates files within a project, and read_file retrieves file contents. There is no overlap or ambiguity in their functions, making it easy for an agent to select the correct tool.
All tool names follow a consistent verb_noun pattern (list_projects, list_files_in_project, read_file) with clear, descriptive verbs. The naming is uniform and predictable, enhancing usability and reducing confusion.
With only 3 tools, the set feels thin for a Unity project management server, as it lacks essential operations like creating, updating, or deleting files or projects. While the tools are well-defined, the count is borderline low for the apparent scope.
The tool surface is significantly incomplete for Unity project management. It covers listing and reading but lacks any write, update, or delete operations (e.g., create_project, write_file, delete_file), which are critical for full lifecycle coverage and will likely cause agent failures in many workflows.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Savecraft serves real save game data and expert game knowledge to AI assistants.
