Unity-MCP
A bridge between Unity and AI assistants using the Model Context Protocol (MCP).
Overview
Unity-MCP is an open-source implementation of the Model Context Protocol for Unity game development. It enables AI assistants to interact with Unity game environments through a standardized interface, allowing for AI-assisted game development, automated testing, scene analysis, and runtime debugging.
Architecture
The architecture has been simplified to use AILogger for persistence, removing the need for a separate server component:
AI Assistant <-> Unity-MCP STDIO Client <-> Unity Client <-> AILogger
- AI Assistant: Communicates with the Unity-MCP STDIO Client using the MCP protocol
- Unity-MCP STDIO Client: Forwards commands to the Unity Client and stores results in AILogger
- Unity Client: Executes commands in Unity and returns results
- AILogger: Stores logs and results for later retrieval
The Unity-MCP STDIO Client communicates directly with the Unity Client, which provides endpoints for both code execution and queries. The query tool transforms queries into code execution by wrapping them in a return statement.
Features
- Execute C# code in the Unity runtime environment
- Inspect game objects and their components
- Analyze scene hierarchies and structures
- Run tests and receive results
- Invoke methods on game objects and components
- Modify game state during runtime
Deployment Options
- Unity Editor Extension: An Editor extension that persists beyond game execution cycles
- Docker Container: A containerized version that communicates with Unity over the network
- NPX Package: A Node.js package that can be installed and run via NPX
Documentation
- MCP Architecture: Overview of the MCP architecture and namespaces
- MCP STDIO Client: Information about the MCP STDIO client and its logging capabilities
- Query Tool: Detailed information about the query tool and how it works
- AILogger Integration: Detailed information about the AILogger integration
- API Reference: Detailed information about the API endpoints
- Installation Guide: Step-by-step instructions for installing and setting up Unity-MCP
- Development Guide: Information about the development environment and workflow
- Hot Reloading Guide: Detailed information about hot reloading in the development environment
- Hot Reloading Quick Reference: Quick reference guide for hot reloading commands and tips
- Contributing Guide: Guidelines for contributing to the project
Getting Started
To get started with Unity-MCP, follow these steps:
-
Clone the repository:
git clone https://github.com/TSavo/Unity-MCP.git cd Unity-MCP -
Install dependencies:
npm install -
Build the project:
npm run build -
Start the MCP STDIO client:
npm startThis will start the MCP STDIO client that communicates with Unity and uses AILogger for persistence.
Note: Make sure AILogger is running on http://localhost:3030 or set the AI_LOGGER_URL environment variable to point to your AILogger instance.
-
Run tests:
# 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"
For more detailed instructions, see the Installation Guide.
Connecting to AI Assistants
To connect the Unity-MCP bridge to an AI assistant, you need to create an MCP configuration file:
{
"mcpServers": {
"unity-ai-bridge": {
"url": "http://localhost:8080/sse"
}
}
}
Place this file in the appropriate location for your AI assistant. For Claude, this would typically be in the Claude Desktop app's configuration directory.
Available Tools
The Unity-MCP bridge provides the following tools:
- execute_code: Execute C# code directly in Unity.
- query: Execute a query using dot notation to access objects, properties, and methods.
- get_logs: Retrieve logs from AILogger.
- get_log_by_name: Retrieve a specific log from AILogger.
Usage Examples
Executing Code in Unity
You can execute C# code in Unity using the execute_code tool. The code will be executed in the Unity runtime environment, and the result will be stored in AILogger for later retrieval.
JSON-RPC Request
{
"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
}
}
}
JSON-RPC Response
{
"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}}"
}
]
}
}
Querying Unity Objects
You can query Unity objects using the query tool. This allows you to access objects, properties, and methods using dot notation.
JSON-RPC Request
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "query",
"arguments": {
"query": "Camera.main.transform.position",
"timeout": 5000
}
}
}
JSON-RPC Response
{
"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}}"
}
]
}
}
Retrieving Results from AILogger
You can retrieve the results of previous operations from AILogger using the get_log_by_name tool.
JSON-RPC Request
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "get_log_by_name",
"arguments": {
"log_name": "unity-execute-1712534400000",
"limit": 1
}
}
}
JSON-RPC Response
{
"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\"}]}"
}
]
}
}
Example Usage
Once the AI assistant has access to the Unity tool, you can ask it to perform tasks like:
Can you execute the following C# code in Unity?
GameObject.Find("Player").transform.position = new Vector3(0, 1, 0);
License
MIT
Author
T Savo (@TSavo)