Unity Code MCP Server

Ferramenta poderosa para o Unity Editor que dá aos Agentes de IA a capacidade de realizar qualquer ação usando a API do Unity Editor, como modificação de scripts, cenas, prefabs, assets, configuração e mais.

GitHub

Experimente este MCPPatrocinado

Documentação

Unity Code MCP Server

Pesquise o projeto Unity ativo

Inspecione cenas ativas, componentes, assets, saída do console, configurações, estado do Play Mode e valores em tempo de execução a partir de um cliente MCP.

Execute diretamente dentro do Editor

Crie e modifique GameObjects, prefabs, ScriptableObjects, configurações de importação e outros assets do Unity executando C# no Editor.

Verifique com feedback em tempo de execução

Execute testes de Edit Mode e Play Mode, entre no Play Mode, simule entrada do jogador, capture capturas de tela, leia logs do console do Unity e inspecione o estado do jogo ao vivo após as ações.

Exemplo de fluxo de trabalho do agente: jogue Pong em um loop fechado usando enter_play_mode, execute_csharp_script_in_unity_editor, play_unity_game e read_unity_console_logs para pesquisar o estado em tempo de execução, executar ações de entrada, verificar o resultado e adaptar o próximo movimento. Play Pong game example

Exemplo de fluxo de trabalho real

Veja o exemplo completo de fluxo de trabalho de cidades e transcrição.

Ferramentas

execute_csharp_script_in_unity_editor

Execute qualquer tarefa executando scripts C# gerados no contexto do Unity Editor. Acesso total às APIs UnityEngine, UnityEditor e reflexão. Captura automaticamente logs, erros e valores de retorno.

read_unity_console_logs

Leia logs do Console do Unity Editor com limites de entrada configuráveis (1-1000, padrão 200)

run_unity_tests

Execute testes do Unity via TestRunnerApi. Suporta EditMode, PlayMode ou ambos. Pode executar todos os testes ou filtrar por nomes de teste totalmente qualificados.

enter_play_mode

Entre no Play Mode do Unity, pause o tempo e retorne imediatamente após acionar a transição. Destinado a ser usado antes das ferramentas de automação de jogabilidade.

play_unity_game

Pause temporariamente o tempo, simule ações configuradas do Input System, colete logs e pause novamente ao terminar.

get_unity_game_view_window_screenshot

Capture a visualização atual do Game View do Unity como uma imagem sem rotear a captura de tela por chamadas de entrada de jogabilidade.

exit_play_mode

Saia do Play Mode do Unity, retome o tempo e retorne imediatamente após acionar a transição.

get_unity_info

Retorna informações sobre o projeto atual do Unity Editor e as configurações do UnityCodeMcpServer.

Considerações de segurança

Este pacote executa código C# gerado por LLM (incluindo código de reflexão) com os mesmos privilégios do processo do Unity Editor. Você é responsável por proteger seu ambiente e por quaisquer alterações ou perda de dados causadas pelos scripts executados.

Arquitetura

diagram
Diagrama de arquitetura: o pacote Unity Code MCP Server é executado dentro do Unity Editor e se comunica com um cliente MCP externo (como um agente LLM) por meio de uma ponte STDIO baseada em arquivos.

Transporte STDIO

graph LR
    A["MCP Client<br/>AI Agent"] -->|STDIO| B["STDIO Bridge<br/>Python script"]
    B <-->|request/response files| C["Unity Code MCP Server<br/>Unity Editor"]

    style A fill:#e1f5ff
    style B fill:#fff3e0
    style C fill:#f3e5f5

Início rápido

Requisitos

Unity 2022.3 LTS ou superior (testado em 2022.3.62f3 e 6000.2.7f2)
uv (gerenciador de pacotes Python) para a ponte STDIO incluída: https://docs.astral.sh/uv/.

Instalação

Instale uv:
- Siga as instruções em https://docs.astral.sh/uv/getting-started/installation
Instale o Unity Code MCP Server pelo Unity Package Manager. Abra Window > Package Manager, clique no botão +, selecione Add package from git URL... e insira:

https://github.com/Signal-Loop/UnityCodeMCPServer.git?path=Assets/Plugins/UnityCodeMcpServer

Configure o local de instalação das habilidades. Abra Tools/UnityCodeMcpServer/Show or Create Settings, role até a seção Skills e confirme ou altere o diretório de instalação. Por padrão, instalações pela primeira vez têm como alvo .agents/skills/. As habilidades são instaladas e atualizadas automaticamente quando o pacote é instalado ou atualizado.

Primeira execução

Configuração do cliente MCP

Abra seu projeto Unity. O Unity inicia automaticamente o transporte baseado em arquivos e observa .unityCodeMcpServer/messages na raiz do projeto.
Configure seu cliente MCP para executar a ponte STDIO incluída.

STDIO

Exemplo de configuração (usando uv para executar a ponte):

A ponte unity-code-mcp-stdio encaminha o tráfego STDIO para o Unity por meio de .unityCodeMcpServer/messages.

{
  "mcpServers": {
    "unity-code-mcp-stdio": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:/path/to/UnityProject/Assets/Plugins/UnityCodeMcpServer/Editor/STDIO~",
        "unity-code-mcp-stdio"
      ]
    }
  }
}

Configuração do servidor (Unity)

Acesse as configurações via Tools/UnityCodeMcpServer/Show or Create Settings.
Configure Verbose Logging para diagnósticos detalhados e, opcionalmente, defina Input Actions Asset para play_unity_game.

O transporte baseado em arquivos troca arquivos de solicitação e resposta por meio de .unityCodeMcpServer/messages na raiz do projeto Unity.

Comandos de menu

Geral

Tools/UnityCodeMcpServer/Show or Create Settings — Abra o asset de configurações do servidor no inspetor

Habilidades do agente

O Unity Code MCP Server inclui um conjunto de arquivos de habilidades do agente de IA (documentos Markdown que ensinam seu agente a usar as ferramentas do servidor de forma eficaz). Essas habilidades são instaladas automaticamente no diretório de destino configurado sempre que o pacote é instalado ou atualizado.

Instalando habilidades

Abra as configurações do servidor: Tools/UnityCodeMcpServer/Show or Create Settings.
Role até a seção Skills.
Escolha o diretório de instalação no menu suspenso:

GitHub tem como alvo .github/skills/
Claude tem como alvo .claude/skills/
Agents tem como alvo .agents/skills/
Custom mostra um seletor de pastas para que você possa selecionar qualquer diretório

O inspetor mostra o rótulo do diretório de destino atualmente selecionado para que você possa verificar exatamente onde as habilidades serão copiadas.
As execuções de instalação e atualização do pacote copiam as habilidades automaticamente.

Somente arquivos .md novos ou alterados são copiados. Arquivos que já estão atualizados (com hash de conteúdo correspondente) são ignorados.

Habilidades incluídas

Skill	Description
`executing-csharp-scripts-in-unity-editor`	Ensina o agente quando e como usar `execute_csharp_script_in_unity_editor`, `read_unity_console_logs` e `run_unity_tests` juntos como um pipeline confiável. Aborda padrões proibidos, loops de depuração e padrões comuns de script.
`unity-game-player`	Ensina o agente a jogar e testar jogos Unity em um loop fechado usando `enter_play_mode`, `play_unity_game`, `execute_csharp_script_in_unity_editor`, `read_unity_console_logs` e `exit_play_mode`. Aborda descoberta de cenas, temporização de ações baseada em matemática e re-sensoriamento adaptativo.

Extensão (adicionando ferramentas)

Adicione ferramentas, prompts, recursos ou ferramentas assíncronas implementando as interfaces relevantes (ITool, IToolAsync, IPrompt, IResource) em qualquer lugar do seu código. O servidor os detectará e registrará automaticamente.

Ferramenta síncrona

using System.Collections.Generic;
using Newtonsoft.Json.Linq;
using UnityCodeMcpServer.Interfaces;
using UnityCodeMcpServer.Protocol;

public class EchoTool : ITool
{
    public string Name => "echo";

    public string Description => "Echoes the input text back to the caller";

    public JToken InputSchema => JsonHelper.ParseElement(@"{
            ""type"": ""object"",
            ""properties"": {
                ""text"": {
                    ""type"": ""string"",
                    ""description"": ""The text to echo""
                }
            },
            ""required"": [""text""]
        }");

    public ToolsCallResult Execute(JToken arguments)
    {
        var text = arguments.GetStringOrDefault("text", "");

        return ToolsCallResult.TextResult($"Echo: {text}");
    }
}

Ferramenta assíncrona

using System.Collections.Generic;
using Newtonsoft.Json.Linq;
using UnityCodeMcpServer.Interfaces;
using UnityCodeMcpServer.Protocol;
using System.Threading.Tasks;

public class DelayedEchoTool : IToolAsync
{
    public string Name => "delayed_echo";

    public string Description => "Echoes the input text after a specified delay (demonstrates async tool)";

    public JToken InputSchema => JsonHelper.ParseElement(@"{
            ""type"": ""object"",
            ""properties"": {
                ""text"": {
                    ""type"": ""string"",
                    ""description"": ""The text to echo""
                },
                ""delayMs"": {
                    ""type"": ""integer"",
                    ""description"": ""Delay in milliseconds before echoing"",
                    ""default"": 1000
                }
            },
            ""required"": [""text""]
        }");

    public async Task<ToolsCallResult> ExecuteAsync(JToken arguments)
    {
        var text = arguments.GetStringOrDefault("text", "");
        var delayMs = arguments.GetIntOrDefault("delayMs", 1000);

        await Task.Delay(delayMs);

        return ToolsCallResult.TextResult($"Delayed Echo (after {delayMs}ms): {text}");
    }
}

Contexto de execução de script

Por padrão, o contexto de execução de script inclui os seguintes assemblies:

Assembly-CSharp
Assembly-CSharp-Editor
System.Core
UnityEngine.CoreModule
UnityEditor.CoreModule

As configurações do Unity Code MCP Server (Assets/Plugins/UnityCodeMcpServer/Editor/Resources/UnityCodeMcpServerSettings.asset) permitem configurar assemblies adicionais para incluir no contexto de execução de script. Isso é útil se o seu projeto tiver assemblies que seus scripts gerados precisam referenciar.

Para adicionar assemblies adicionais, use a seção 'Additional Assemblies' das configurações.

Additional Assemblies

Ponte STDIO

Veja a documentação da ponte em README_STDIO.md.

Testes

Os testes do Unity estão em Assets/Tests/ e podem ser executados via Unity Test Runner.

Problemas conhecidos

Conflitos de GUID com arquivos dll existentes no projeto

O Unity Code MCP Server inclui arquivos dll em seu pacote. Se esses arquivos já estiverem presentes no seu projeto, você poderá ver conflitos de GUID. Em nossos casos de teste, isso não causa problemas, mas se você encontrar problemas, preencha o problema: Issues. Remover dlls duplicados do seu projeto pode resolver os conflitos.

GUID [eb9c83041c7a89c46bb6e20eab4484df] for asset 'Packages/com.signal-loop.unitycodemcpserver/Editor/Bin/Microsoft.CodeAnalysis.CSharp.dll' conflicts with:
  '[Path to dll file in your project]/Microsoft.CodeAnalysis.CSharp.dll' (current owner)
We can't assign a new GUID because the asset is in an immutable folder. The asset will be ignored.

Licença

MIT