unity-mcp MCP — Cas d'usage, Installer & Démo en direct

Pourquoi l'utiliser

Fonctionnalités clés

40+ outils granulaires de l'Éditeur Unity (scène, assets, scripts, tests, physique, UI, VFX)
apply_text_edits sécurisées pour les scripts C# avec validation avant écriture
Lisez la console Unity (erreurs/avertissements) et déclenchez les rechargements de domaine
Exécutez les tests EditMode et PlayMode et lisez les résultats
Prend en charge plusieurs instances Unity avec routage par instance

Démo en direct

Aperçu en pratique

unity.replay ▶ prêt

0/0

Installer

Choisissez votre client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Ouvrez Claude Desktop → Settings → Developer → Edit Config. Redémarrez après avoir enregistré.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Cursor utilise le même schéma mcpServers que Claude Desktop. La config projet l'emporte sur la globale.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Cliquez sur l'icône MCP Servers dans la barre latérale Cline, puis "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "unity": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ],
      "_inferred": true
    }
  }
}

Même format que Claude Desktop. Redémarrez Windsurf pour appliquer.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "unity",
      "command": "TODO",
      "args": [
        "See README: https://github.com/CoplayDev/unity-mcp"
      ]
    }
  ]
}

Continue utilise un tableau d'objets serveur plutôt qu'une map.

~/.config/zed/settings.json

{
  "context_servers": {
    "unity": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/CoplayDev/unity-mcp"
        ]
      }
    }
  }
}

Ajoutez dans context_servers. Zed recharge à chaud à la sauvegarde.

claude mcp add unity -- TODO 'See README: https://github.com/CoplayDev/unity-mcp'

Une seule ligne. Vérifiez avec claude mcp list. Supprimez avec claude mcp remove.

Cas d'usage

Usages concrets : unity-mcp

Comment créer un prototype de scène Unity à partir d'une description textuelle

👤 Concepteurs de jeux, développeurs solo, équipes de hackathon ⏱ ~20 min intermediate

Quand l'utiliser : Vous voulez passer de 'forêt basse polygonale avec un joueur et 5 ennemis en patrouille' à une scène exécutable sans câbler manuellement chaque GameObject.

Prérequis

Unity 2021.3 LTS ou plus récent, Python 3.10+, uv — Installez uv via brew install uv ; Unity depuis unity.com/download
Installez le package Unity — Window > Package Manager > + > Add from git URL: https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#main

Déroulement

Décrivez la scène que vous voulez

Créez une nouvelle scène appelée 'ForestDemo'. Ajoutez un terrain basse polygonale 200x200, une capsule joueur à l'origine avec un rigidbody, et 5 ennemis cube placés aléatoirement entre (-50,-50) et (50,50).✓ Copié

→ Scène créée, les GameObjects apparaissent dans la Hiérarchie, Unity reflète les modifications en temps réel
Demandez des scripts de comportement

Créez un script C# EnemyPatrol.cs qui se déplace entre deux points de passage aléatoires, et attachez-le à chaque GameObject Enemy*.✓ Copié

→ Le nouveau script se compile sans erreur, attaché aux ennemis
Entrez en mode Lecture et itérez

Entrez en mode Lecture pendant 5 secondes, puis lisez la console et dites-moi si quelque chose a levé une exception.✓ Copié

→ Journal d'exécution retourné, Claude propose des correctifs concrets pour toute NullReferenceException

Résultat : Une scène de prototype exécutable avec des ennemis scriptés — moins de 15 minutes de chat.

Pièges

Les modifications de script sont rejetées à cause d'erreurs de compilation en cascade — Demandez à Claude d'exécuter manage_script validate avant apply_text_edits
Le rechargement de domaine efface l'état d'exécution en milieu de session — Enregistrez la scène explicitement avant les modifications de script ; utilisez refresh_unity ensuite

Combiner avec : github · filesystem

Comment diagnostiquer et corriger les erreurs de compilation/exécution Unity depuis le chat

👤 Développeurs Unity bloqués sur une console rouge ⏱ ~15 min intermediate

Quand l'utiliser : La console est remplie d'erreurs d'une grande refonte ou d'une mise à jour de package et vous voulez un second avis.

Déroulement

Tirez la console

Lisez la console Unity. Groupez les erreurs par cause racine.✓ Copié

→ Catégories d'erreurs groupées avec les fichiers probables identifiés
Lisez le script incriminé

Ouvrez le premier script mentionné, trouvez la ligne et expliquez pourquoi elle se casse.✓ Copié

→ Proposition de correctif spécifique référençant les numéros de ligne
Appliquez un correctif minimal

Appliquez le plus petit changement pour le faire compiler, puis actualisez Unity et relisez la console.✓ Copié

→ Le nombre d'erreurs diminue, aucune nouvelle erreur introduite

Résultat : Une console verte et un diff que vous pouvez vérifier avant de commit.

Pièges

Claude propose des correctifs qui cassent les contrats d'API pour les autres scripts — Demandez-lui de trouver les références (find_in_file) avant de modifier

Combiner avec : github

Comment exécuter les tests EditMode/PlayMode Unity et lire les défaillances

👤 Devs Unity avec une suite de tests réelle ⏱ ~15 min intermediate

Quand l'utiliser : Avant d'ouvrir une PR ou quand l'intégration continue est indisponible et vous voulez un passage rapide en local.

Déroulement

Lancez une exécution de test

Exécutez tous les tests EditMode dans l'assembly Tests.EditMode.✓ Copié

→ L'ID du travail de test est retourné, le statut est transmis en streaming
Résumez les défaillances

Pour chaque test qui échoue, affichez le message d'assertion et la ligne qu'il a déclenchée.✓ Copié

→ Diagnostic par test
Corrigez d'abord la plus petite défaillance

Choisissez la défaillance la plus probablement causée par ma dernière modification et proposez un correctif.✓ Copié

→ Suggestion de modification concrète

Résultat : Une exécution de test verte avec des modifications traçables.

Pièges

Les tests PlayMode nécessitent un assembly différent — Spécifiez explicitement EditMode vs PlayMode

Combiner avec : github

Combinaisons

Associez-le à d'autres MCPs pour un effet X10

unity + github

Générez une scène + scripts, commitez les modifications, ouvrez une PR pour révision

Créez la fonctionnalité EnemyPatrol dans Unity, commitez le nouveau script et les modifications de scène vers une branche 'feature/enemy-patrol', et ouvrez une PR avec un résumé des modifications.✓ Copié

unity + filesystem

Importez un lot d'assets 3D d'un dossier local et connectez-les dans des préfabs

Lisez /Downloads/kenney-nature-pack, importez chaque .fbx dans Assets/Models/, puis créez un préfab pour chaque arbre avec un collider.✓ Copié

unity + unity-2 + unity-3

Choisissez l'MCP Unity qui correspond le mieux à votre flux de travail — exécutez un seul à la fois

Comparez MCP for Unity vs CoderGamester mcp-unity pour mon projet tilemap 2D, puis gardez le meilleur activé.✓ Copié

Outils

Ce que ce MCP expose

Outil	Entrées	Quand appeler	Coût
manage_scene	action: 'create'\|'open'\|'save'\|'load', name?: str, path?: str	Tout changement du cycle de vie de la scène	free
find_gameobjects	query: str, scene?: str	Localisez les objets par nom, balise ou composant	free
manage_components	target: str, action: 'add'\|'remove'\|'modify', component: str, values?: obj	Attachez ou ajustez les composants	free
manage_script	action: 'create'\|'read'\|'delete', path: str, body?: str	Écritures de script complet — utilisez apply_text_edits pour les modifications partielles	free
apply_text_edits	path: str, edits: Edit[]	Correctifs chirurgicaux ; plus sûrs que les réécritures complètes	free
read_console	since_ms?: int	Inspectez les erreurs/avertissements après toute modification	free
run_tests	mode: 'EditMode'\|'PlayMode', filter?: str	Lancez une exécution de test ; interrogez avec get_test_job	free
refresh_unity		Après la création/modification de scripts ou d'assets	free
manage_asset	action, path, ...	Importez/déplacez/supprimez des assets	free
unity_docs	query: str	Recherchez la documentation de l'API Unity en ligne	free

Coût et limites

Coût d'exécution

Quota d'API: Pas d'API distante — s'exécute entièrement sur votre machine
Tokens par appel: Lecture de la hiérarchie de scène : 500-3000 tokens. Lectures de script : dépend de la taille du fichier
Monétaire: Gratuit (open source, MIT)
Astuce: Désactivez les outils que vous n'utiliserez pas (par exemple manage_vfx, manage_probuilder) via la liste blanche des outils pour réduire l'empreinte du prompt.

Sécurité

Permissions, secrets, portée

Portées minimales : écriture du système de fichiers local dans votre projet Unity

Stockage des identifiants : Aucun nécessaire — HTTP localhost uniquement

Sortie de données : Localhost uniquement (http://localhost:8080/mcp). Pas de télémétrie par défaut.

Ne jamais accorder : accès aux projets Unity en dehors du projet actif

Les modifications de script pilotées par l'IA peuvent casser votre projet — commitez avant les longues sessions.
run_tests en PlayMode exécute le code du jeu ; traitez-le comme le ferait 'play', avec tous les effets secondaires.

Dépannage

Erreurs courantes et correctifs

Claude ne peut pas se connecter : ECONNREFUSED localhost:8080

L'Éditeur Unity doit être ouvert avec le package MCP chargé. Vérifiez Window > MCP for Unity > Status.

Vérifier : curl http://localhost:8080/mcp/ping

apply_text_edits signale 'fichier modifié sur le disque'

Un autre outil a modifié le fichier. Relisez avec manage_script avant de modifier à nouveau.

refresh_unity se bloque indéfiniment

Généralement une erreur de compilation verrouillant le rechargement du domaine. Ouvrez Unity, corrigez le script rouge, puis réessayez.

Vérifier : Vérifiez manuellement la console Unity

Package Manager 'Impossible de résoudre l'URL git'

Derrière un proxy ou pas de git dans le PATH. Installez git et réessayez, ou utilisez l'installation OpenUPM à la place.

Vérifier : git --version

Alternatives

unity-mcp vs autres

Alternative	Quand l'utiliser	Compromis
Unity-MCP (IvanMurzak)	Vous voulez une installation basée sur CLI et une exécution C# basée sur Roslyn	Communauté plus petite que celle de Coplay, surface d'outils différente
mcp-unity (CoderGamester)	Vous voulez un ensemble d'outils plus simple centré sur la manipulation de scène et les tests	Moins d'outils, moins de couverture des matériaux/VFX

Plus

Ressources

📖 Lire le README officiel sur GitHub

🐙 Voir les issues ouvertes

🔍 Parcourir les 400+ serveurs MCP et Skills