Godot MCP

300+ ferramentas que conectam assistentes de IA diretamente ao editor Godot. Crie cenas, escreva scripts, teste a jogabilidade — tudo por meio de linguagem natural.

GitHub
21
Experimente este MCPPatrocinado

Documentação

Godot MCP

Desenvolvimento de jogos com IA para Godot Engine via Model Context Protocol

TypeScript GDScript Godot 4.x MCP License: MIT

🌐 Website · 📋 Catálogo de Ferramentas · 💬 GitHub · 📦 Releases

O Godot MCP conecta assistentes de IA (Claude, Cursor, VS Code Copilot, OpenCode e qualquer cliente compatível com MCP) diretamente ao editor Godot. Ele expõe mais de 300 ferramentas em mais de 40 módulos, cobrindo desde construção de cenas e manipulação de nós até inspeção em tempo de execução, gravação de entrada, configuração de física, autoria de animações, exportação de projetos, gerenciamento de addons, depuração e configuração específica de plataforma.

A IA pode ler sua árvore de cenas, criar nós, escrever scripts, simular entrada de jogo, capturar capturas de tela, executar asserções e modificar propriedades em lote entre cenas, tudo por meio de uma única ponte WebSocket.

Este projeto foi desenvolvido com a ajuda de vários modelos de IA: MiMo-V2.5-Pro, DeepSeek V4 Pro, DeepSeek V4 Flash e Qwen 3.7 Plus.

Sumário

Recursos

  • Mais de 300 ferramentas para fluxos de trabalho completos de desenvolvimento Godot
  • Manipulação de cenas em tempo real — adicione, exclua, mova, renomeie e reconfigure nós sem sair do seu chat de IA
  • Inspeção do jogo em tempo de execução — consulte a árvore de cenas ativa, leia/grave propriedades durante o gameplay, execute GDScript no jogo em execução
  • Gravação e reprodução de entrada — grave sessões de jogadores, reproduza em velocidade variável, simule entrada de teclado/mouse/ação
  • Testes visuais com capturas de tela — capture capturas de tela do editor e do viewport do jogo para verificações de regressão visual
  • Autoria de animações — crie clipes, adicione trilhas, defina keyframes, construa máquinas de estado e blend trees
  • Configuração de física — adicione corpos, formas de colisão, raycasts, materiais de física; configure camadas/máscaras
  • Gerenciamento de áudio — adicione players, configure layouts de barramento, insira efeitos (reverb, delay, chorus, etc.)
  • Navegação — configure regiões, agentes, gere navmeshes, consulte pathfinding entre pontos
  • Edição de TileMap — defina células, preencha retângulos, limpe áreas, leia dados de tiles
  • Ferramentas de tema e shader — crie temas, defina cores/fontes/styleboxes; crie, edite e valide shaders
  • Operações em lote — encontre nós por tipo, defina propriedades entre cenas, detecte dependências circulares
  • Estrutura de testes — execute cenários de teste em várias etapas, verifique o estado dos nós, verifique texto na tela, execute testes de estresse
  • Suporte a desfazer/refazer — todas as mutações do editor passam pelo sistema de desfazer integrado do Godot
  • Varredura automática de portas — servidor e plugin negociam nas portas 6505-6514 automaticamente
  • Modificação zero do projeto — instala-se como um plugin Godot padrão, sem exigir alterações no mecanismo

Arquitetura

MCP Client (Claude, Cursor, VS Code, OpenCode)
    │  stdio (JSON-RPC 2.0)
    ▼
Node.js MCP Server (TypeScript)
    │  WebSocket (JSON-RPC 2.0)
    ▼
Godot Editor Plugin (GDScript)
    ├── Command Router → 40+ command modules → 300+ tools
    ├── UndoRedo Helper
    └── Runtime Autoload (mcp_runtime.gd)
        — scene tree queries, property R/W, input simulation,
          screenshot capture, signal watching

Fluxo de dados: o cliente de IA envia uma chamada de ferramenta via stdio → o servidor MCP procura a ferramenta no registro → encaminha via WebSocket para o plugin Godot → o roteador de comandos despacha para o módulo correto → o módulo chama a API do Editor Godot (com desfazer/refazer) → o resultado retorna ao cliente de IA.

Consulte o website para ver um diagrama detalhado da arquitetura.

Instalação

Pré-requisitos

  • Godot 4.x (testado com 4.7)
  • Um cliente de IA compatível com MCP (Claude Desktop, Cursor, VS Code com Copilot, OpenCode, etc.)

Addon Godot

Opção A — Baixar dos Releases (recomendado)

  1. Vá para a página de Releases e baixe o asset zip addons mais recente (ex.: keeveeg-godot-mcp-v1.1.0-addons.zip).
  2. Extraia o zip na raiz do seu projeto Godot — isso coloca addons/godot_mcp/ no local correto.
  3. Abra seu projeto no Godot.
  4. Vá em Projeto → Configurações do Projeto → Plugins.
  5. Encontre o Godot MCP na lista e defina-o como Ativo.

Opção B — Copiar do repositório

  1. Copie a pasta addons/godot_mcp/ deste repositório para o diretório addons/ do seu projeto.
  2. Abra seu projeto no Godot.
  3. Vá em Projeto → Configurações do Projeto → Plugins.
  4. Encontre o Godot MCP na lista e defina-o como Ativo.

Após ativar, o plugin verifica as portas 6505-6514 em busca de um servidor MCP em execução. Uma vez conectado, a aba MCP aparece no painel inferior mostrando o status da conexão e o log de atividades.

Configuração

Cliente MCP

Adicione o seguinte ao arquivo de configuração do seu cliente MCP:

{
  "mcpServers": {
    "godot": {
      "command": "npx",
      "args": ["-y", "@keeveeg/godot-mcp"]
    }
  }
}

Para desenvolvimento local, use o caminho completo:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["/path/to/godot-mcp/server/dist/index.js"]
    }
  }
}
ClienteArquivo de configuração
Claude Desktop~/.config/claude/claude_desktop_config.json (Linux/macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows)
Cursor.cursor/mcp.json na raiz do projeto
OpenCodeopencode.json na raiz do projeto ou ~/.config/opencode/opencode.json globalmente

Exemplo de opencode.json:

{
  "mcp": {
    "godot": {
      "type": "local",
      "command": ["npx", "-y", "@keeveeg/godot-mcp"]
    }
  }
}

Variáveis de Ambiente

VariávelPadrãoDescrição
GODOT_MCP_DEBUG(não definido)Defina para qualquer valor para habilitar o log de depuração no servidor

Ativar/Desativar Ferramentas

Crie um arquivo godot_mcp_config.json na raiz do seu projeto Godot para desativar ferramentas seletivamente:

{
  "enabled_tools": {
    "delete_scene": false,
    "reload_project": false,
    "execute_editor_script": false
  }
}

Ferramentas não listadas na configuração ficam ativadas por padrão. O plugin lê esse arquivo na inicialização.

Ferramentas

Todas as mais de 300 ferramentas em mais de 40 módulos estão documentadas no Catálogo de Ferramentas com descrições pesquisáveis e agrupamentos por categoria.

Solução de Problemas

Problemas de Conexão

"Godot editor is not connected"

O servidor MCP está em execução, mas o Godot ainda não se conectou.

  • Certifique-se de que o editor Godot esteja aberto com o plugin MCP ativo
  • Verifique o painel MCP na doca inferior do Godot para ver o status da conexão
  • Verifique se nenhum firewall está bloqueando conexões localhost nas portas 6505-6514
  • Observe o log de saída do Godot em busca de mensagens [MCP]

"Failed to bind to any port in range 6505-6514"

Todas as portas no intervalo de varredura estão ocupadas.

  • Verifique se outra instância do servidor MCP já está em execução
  • Encerre quaisquer processos node antigos: pkill -f "godot-mcp" (Linux/macOS) ou use o Gerenciador de Tarefas (Windows)
  • O servidor tentará automaticamente a próxima porta disponível

Caminho do Godot Não Encontrado

  • Use caminhos com prefixo res:// (ex.: res://scenes/main.tscn)
  • Use get_filesystem_tree para verificar a estrutura do projeto
  • Certifique-se de que o projeto Godot é o que você pensa que é (verifique get_project_info)

Tempo Limite do WebSocket

"Request timed out after 30000ms"

  • O editor pode estar ocupado (compilando, carregando uma cena grande)
  • Verifique se um diálogo está bloqueando o editor (o plugin dispensa automaticamente a maioria dos diálogos durante o gameplay)
  • Tente a solicitação novamente — para operações grandes, o editor pode precisar de mais tempo

Plugin Não Carregando

  • Verifique se o diretório addons/godot_mcp/ está no local correto
  • Vá em Projeto → Configurações do Projeto → Plugins e verifique se o Godot MCP aparece
  • Se aparecer, mas estiver desativado, ative-o
  • Verifique se há erros de GDScript no log de saída
  • Tente Projeto → Recarregar Projeto Atual

Ferramentas de Tempo de Execução Não Funcionam

O autoload mcp_runtime.gd deve estar presente para que as ferramentas de tempo de execução funcionem. O plugin o registra automaticamente, mas verifique:

  1. Abra project.godot e verifique a seção [autoload]
  2. Você deve ver: mcp_runtime="res://addons/godot_mcp/services/mcp_runtime.gd"
  3. Importante: NÃO use o prefixo * — o * significa "somente editor" e o autoload não carregará no jogo
  4. Verifique o log de saída do Godot em busca de [MCP Runtime] Loaded and ready for IPC