Referência da CLI
Referência completa do unreal-mcp-cli: instale o plugin Unreal MCP, faça login, configure agentes de IA, abra o editor e execute Python.
unreal-mcp-cli é a ferramenta de linha de comando do Unreal MCP. Ela instala e atualiza o plugin, faz login no ai-game.dev, grava configs MCP para agentes de IA, inicia o Unreal Editor com as configurações de conexão corretas e chama ferramentas a partir de scripts e CI. Funciona no Windows, macOS e Linux. Esta página cobre a versão 0.26.2.
Instalar a CLI
Requer Node.js ^20.19.0 ou >=22.12.0.
npm install -g unreal-mcp-cli
unreal-mcp-cli --versionOu execute um único comando sem instalar:
npx unreal-mcp-cli@latest statusExecute unreal-mcp-cli <command> --help para a ajuda integrada de qualquer comando. A flag global -v, --verbose imprime diagnósticos extras.
Observação: comandos que recebem o projeto como [path] o aceitam como argumento posicional. Comandos sem [path] o recebem com -p, --path <dir>. Ambos usam a pasta atual como padrão. Passar um caminho posicional para um comando --path falha com "too many arguments".
Visão geral dos comandos
| Comando | Finalidade |
|---|---|
create-project <path> | Cria a estrutura de um projeto C++ mínimo do Unreal Engine |
install-plugin [path] | Instala o plugin UnrealMCP em <project>/Plugins |
update [path] | Atualiza o plugin instalado |
remove-plugin [path] | Remove o plugin |
install-extension <id> [path] | Instala uma extensão do Unreal MCP |
login | Faz login no ai-game.dev (fluxo de código de dispositivo) |
configure | Grava valores UNREAL_MCP_* em <project>/.env |
setup-mcp [agent] | Grava uma config MCP para um agente de IA |
setup-skills | Grava uma skill do Claude Code para o projeto |
open [path] | Inicia o Unreal Editor com as configurações de conexão |
close [path] | Fecha o editor que está executando o projeto |
exec [code] | Executa Python no editor |
status | Mostra o estado do pacote, projeto, plugin e conexão |
wait-for-ready | Aguarda até o servidor MCP do projeto responder |
run-tool <tool> | Chama uma ferramenta MCP via HTTP |
run-system-tool <tool> | Chama uma ferramenta de sistema via HTTP |
bootstrap-local [path] | Compila a bridge a partir do código-fonte |
install-engine [version] | Detecta engines instaladas, faz link com o Epic launcher |
Comandos de configuração do projeto
create-project
Cria a estrutura de um projeto C++ mínimo. Opções: --name <name> (nome do projeto e do módulo; letras, dígitos e underscores, sem hífens), --engine <version> (o EngineAssociation, por exemplo 5.7), --force (permite uma pasta não vazia).
unreal-mcp-cli create-project ./MyGame --engine 5.7install-plugin
Instala o plugin. Sem um código-fonte local, baixa do release do GitHub o código-fonte do plugin correspondente à versão da CLI e verifica sua assinatura antes.
| Flag | Significado |
|---|---|
--version <v> | Release do plugin a baixar (padrão: a versão da CLI) |
--plugin-source <dir> | Usa uma pasta local do plugin (offline, CI, desenvolvimento) |
--junction | Link em vez de cópia (Windows, para desenvolvimento do plugin) |
--with-server | Também baixa o gamedev-mcp-server com checksum verificado |
--server-version <v>, --server-source <path-or-url> | Versão do servidor, ou uma origem local ou personalizada, para --with-server |
--enroll <code>, --enroll-stdin | Resgata um código de enrollment de agente em vez de fazer login pelo navegador |
--base-url <url> | URL base de autenticação para --enroll |
-y, --yes | Confirma a troca da máquina para outra conta |
update
Ressincroniza o plugin instalado. Em uma mudança de versão, remove o Intermediate/ obsoleto e os Binaries/ de C++ para que o Unreal recompile do zero, mantendo a bridge incluída. Flags: --version <v>, --plugin-source <dir>, --force (reinstala a mesma versão), --no-clean (mantém o cache de build).
remove-plugin
Remove Plugins/UnrealMCP do projeto. Sem opções.
install-extension
Instala uma extensão, a habilita junto com seu plugin de engine no .uproject. Flags: --version <x.y.z>, --source <dir>, --build (compila agora), --engine-root <dir> (engine para --build), --force.
unreal-mcp-cli install-extension com.ivanmurzak.unreal-ai-pcg ./MyGame --buildbootstrap-local
Compila a bridge a partir do código-fonte em <project>/Intermediate/UnrealMCP/ para checkouts de código-fonte; requer o SDK do .NET 9. Flags: --repo-root <dir>, --plan (apenas imprime o plano de build).
install-engine
Lista as engines instaladas ou verifica uma versão específica. Nunca baixa uma engine; para uma versão ausente, fornece um link do Epic Games Launcher. Flags: --manifest <path> (LauncherInstalled.dat explícito), --install, --yes.
Comandos de login e de agentes de IA
login
Faz login com o fluxo OAuth de código de dispositivo e salva a credencial em ~/.ai-game-dev/credentials.json, compartilhada por todas as ferramentas do AI Game Dev na máquina.
| Flag | Significado |
|---|---|
-p, --path <dir> | Salva a credencial no .env desse projeto em vez do armazenamento da máquina |
--tools-only | Cria uma credencial somente de ferramentas para runners de CI (o app não pode usá-la) |
-y, --yes | Confirma a troca da máquina para outra conta |
--base-url <url> | URL base de autenticação (padrão https://ai-game.dev) |
--timeout <ms> | Timeout total de polling |
configure
Grava valores UNREAL_MCP_* em <project>/.env e adiciona .env ao gitignore. Flags: -p, --path, --mode <Cloud|Custom>, --host <url>, --cloud-url <url>, --token <token>, --auth <option>, --keep-connected, --tools <list>, --start-server, --transport <stdio|http>, --log-level <level>, --no-gitignore.
Com --agent <id>, em vez disso, pede ao gamedev-mcp-server gerenciado que grave uma config de cliente fixada; as flags relacionadas são --url, --server-version e --server-source.
setup-mcp
Grava uma entrada de config MCP para um agente. Veja Conectando clientes de IA para a lista de agentes.
| Flag | Significado |
|---|---|
-p, --path <dir> | Pasta do projeto |
--transport <t> | http (padrão) ou stdio (baixa o servidor local) |
--url <url> | URL do servidor explícita |
--token <token> | Bearer token explícito; tem precedência sobre a chave do projeto |
--oauth | Cloud: config apenas com URL, o próprio agente faz login |
--regenerate-key | Cloud: cria uma nova chave de projeto e revoga a antiga |
--no-pin | URL /mcp simples em vez de /mcp/p/<pin> fixada ao projeto |
--dry-run | Imprime o snippet sem gravá-lo |
--list | Lista os agentes suportados e os caminhos de config |
setup-skills
Grava .claude/skills/unreal-mcp/SKILL.md. Flags: -p, --path, --url, --token, --force (sobrescreve).
Comandos do editor
open
Inicia o Unreal Editor e passa as configurações de conexão como variáveis de ambiente UNREAL_MCP_*. A engine vem do EngineAssociation do projeto; uma engine compilada a partir do código-fonte precisa de --engine-root.
| Flag | Significado |
|---|---|
--connection-mode <mode> | Custom ou Cloud; apenas --host já implica Custom |
--host, --token, --auth, --tools, --transport | Define a variável UNREAL_MCP_* correspondente |
--keep-connected, --start-server | Define a variável correspondente como true |
--no-connect | Não passa nenhuma variável UNREAL_MCP_* |
--headless | Inicia um editor sem janela controlado pela CLI e aguarda até que ele esteja pronto |
--idle <seconds>, --url <url> | Encerramento por inatividade e URL do servidor para um editor controlado pela CLI |
--engine-root <dir> | Pasta da engine para builds a partir do código-fonte |
--no-build | Pula o build pré-lançamento dos módulos nativos |
--no-auto-dismiss-startup-dialogs | Deixa os prompts de inicialização do Unreal como estão |
--startup-dismiss-timeout-ms, --startup-dismiss-poll-interval-ms | Ajusta a dispensa de prompts (padrões 12000 e 1000) |
--no-cache | Redescobre o caminho da engine |
No Linux, a dispensa de prompts de inicialização funciona apenas no X11.
close
Fecha o editor que está executando o projeto. Com --owned-only, fecha apenas um editor iniciado pela CLI (via exec ou open --headless), que salva e encerra; um editor aberto por você nunca é afetado. --force mata um editor controlado pela CLI que não encerra a tempo; --token substitui o bearer token.
exec
Executa Python no editor por meio de python-execute. Reutiliza um editor em execução ou inicia um headless que renderiza fora da tela (para que os screenshots continuem funcionando) e encerra após um período sem chamadas de ferramentas.
unreal-mcp-cli exec "unreal.SystemLibrary.get_engine_version()" -p ./MyGameFlags: -p, --path, -f, --file <file> (- para stdin), --include <path> (helpers de .ai-game-dev/snippets, repetível), --window, --idle <seconds> (padrão 300, 0 = nunca), --ready-timeout <ms>, --timeout <ms>, --raw (imprime a resposta JSON), --url, --token, --engine-root, --no-build. Os resultados são impressos em stdout; print() e linhas de log em stderr.
Comandos de ferramentas e status
status e wait-for-ready
status informa a CLI, o projeto, o plugin e a conexão, com uma sondagem de alcance ao vivo (--no-probe a pula). wait-for-ready bloqueia até o servidor responder a um ping (--timeout, padrão 120000 ms; --interval, padrão 2000 ms). Ambos aceitam -p, --path, --url e --token.
run-tool e run-system-tool
Chama uma ferramenta pelo servidor MCP local do projeto:
unreal-mcp-cli run-tool rql-query -p ./MyGame --input '{"query":"actors | select Label"}'
unreal-mcp-cli run-system-tool ping -p ./MyGameFlags: -p, --path, --url, --token, --input <json>, --input-file <file> (- para stdin), --timeout <ms> (padrão 60000).
A mesma lógica está disponível como uma biblioteca tipada (import { openProject, runTool } from 'unreal-mcp-cli'), usada pelo app AI Game Dev.