MCP

mmd-mcp : piloter MikuMikuDance et les réglages MME sous Windows avec MCP

mmd-mcp est idéal pour piloter par programme MikuMikuDance sous Windows afin de produire des animations et régler les effets MME, à condition d'avoir d'abord lancé soi-même MMD 9.32 x64 en version japonaise et d'avoir effectué une installation depuis les sources nécessitant les composants C++ de Visual Studio.

Official source · mmd-mcp

Install

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
cmd /c scripts\build_native.cmd

mmd-mcp est un serveur MCP stdio destiné à Windows, permettant de piloter les opérations d'animation de MikuMikuDance (MMD) ainsi que les réglages d'effets MME. Ses prérequis sont clairs : vous devez être sous Windows, avoir déjà lancé vous-même MMD 9.32 x64 (la version japonaise ; le serveur refuse les versions non prises en charge), et être prêt à effectuer une installation depuis les sources (nécessite Python x64 et le composant « Développement Desktop en C++ » de Visual Studio 2022/Build Tools). Il ne lance pas MMD automatiquement et n'écoute pas sur le réseau. Si votre environnement ne remplit pas ces conditions, ou si vous ne voulez pas toucher à une chaîne de compilation, ce n'est pas un bon premier choix.

À qui ça s'adresse

  • Ceux qui produisent des animations MMD sous Windows et ont besoin d'ajuster de manière programmatique les modèles, la caméra, les lumières, la physique ou la timeline, ou d'éditer les affectations d'effets EMM de MME et d'exporter des vidéos AVI.
  • Environnement de validation : MMD 9.32 x64 en version japonaise, Windows japonais, Python 3.10 x64 ; les autres versions de MMD sont refusées, les utilisateurs d'autres versions doivent donc être considérés comme non pris en charge.
  • Pas adapté : aux utilisateurs de macOS/Linux, à ceux qui n'ont pas encore installé MMD ou qui utilisent une version non validée, ainsi qu'à ceux qui ne veulent pas installer les composants C++ de Visual Studio. Les preuves officielles ne mentionnent aucune prise en charge de macOS/Linux ; ce point est inconnu.

Première tentative en 3 minutes

Attention : ce chemin principal ne s'exécute pas en 3 minutes ; la compilation du DLL depuis les sources prend un certain temps. « 3 minutes » fait référence au nombre réduit d'étapes.

Prérequis :

  1. Environnement Windows avec Python x64 installé (environnement validé : 3.10 x64).
  2. Visual Studio 2022 ou Build Tools installé, avec le composant « Développement Desktop en C++ » (pour compiler le DLL natif).
  3. La version japonaise de MMD 9.32 x64 déjà lancée — le serveur ne démarre pas MMD automatiquement.

Installation (dans le répertoire du dépôt, commandes PowerShell officielles) :

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
cmd /c scripts\build_native.cmd

La troisième commande compile le DLL natif ; c'est une étape obligatoire et le résultat de compilation reste en local.

Enregistrement auprès du client MCP (mode stdio), exemple de configuration officiel :

"command": "C:/Tools/mmd-mcp/.venv/Scripts/python.exe",
"args": ["-m", "mmd_mcp.server"]

Remplacez le chemin par l'emplacement de votre propre venv.

Pour le premier appel, mmd_list_windows est recommandé : il se contente de lister les fenêtres sans modifier la scène ; c'est le premier appel le moins risqué. Le signal de succès est le retour de la liste des fenêtres MMD actuelles avec leurs hwnd. Si plusieurs instances de MMD sont lancées, chaque appel suivant devra transmettre le hwnd retourné par mmd_list_windows. Les sources officielles ne précisent pas si mmd_list_windows est marqué comme indicateur readOnlyHint (lecture seule) : ne considérez aucun outil comme totalement sans risque.

Autres méthodes d'installation : les sources officielles ne décrivent que le chemin d'installation ci-dessus depuis les sources ; aucun paquet pip ni binaire précompilé n'est mentionné.

Cas d'usage

Cas 1 : vérifier la connexion et gérer plusieurs instances. Scénario : vous venez de configurer votre client et voulez vérifier qu'il trouve MMD. Appelez mmd_list_windows et observez la liste des fenêtres et les hwnd retournés. Si un seul MMD est ouvert, vous pouvez ensuite appeler directement les autres outils ; si plusieurs MMD sont ouverts, transmettez le hwnd correspondant à chaque appel, conformément à la documentation officielle, pour cibler la bonne instance. Vous pouvez valider jusqu'à ce point : l'énumération des fenêtres et le mécanisme de transmission du hwnd ; pour le reste, le format détaillé des sorties dépend des retours réels.

Cas 2 : écriture en masse de keyframes de caméra et export vidéo. Scénario : vous avez finalisé une animation et souhaitez régler les mouvements de caméra de manière programmatique puis exporter en AVI. La version officielle v0.3.0 propose 50 outils, parmi lesquels mmd_batch_camera_keys permet d'écrire en masse des keyframes de caméra et mmd_export_video d'exporter en AVI. Attention : ce sont deux opérations d'écriture sur le projet MMD en cours : l'écriture de keyframes et l'export vidéo modifient/génèrent du contenu du projet ; avant tout appel, vérifiez que le projet ouvert peut être modifié ou dispose déjà d'une sauvegarde. Les preuves officielles n'indiquent pas si ces outils disposent d'un chemin d'annulation, ni le détail des paramètres d'export ; avant tout appel, vérifiez les définitions précises des paramètres dans votre client.

Limites d'utilisation

  • Nature lecture/écriture : parmi les 50 outils, on trouve aussi bien des appels de consultation (fenêtres/scène) que des opérations d'écriture comme la sélection de modèles, l'écriture en masse de keyframes de caméra et de squelettes, la lecture/écriture des affectations d'effets EMM (mmd_read_effect_assignments / mmd_write_effect_assignments) ou l'export AVI. Les opérations d'écriture s'appliquent directement au projet MMD que vous avez ouvert.
  • Liaison à l'environnement : l'environnement validé est strictement MMD 9.32 x64 (version japonaise, vérifiée officiellement par un SHA-256 spécifique) ; les builds non pris en charge sont refusés.
  • Prérequis et effets de bord : MMD doit être lancé manuellement au préalable ; le serveur ne démarre pas MMD et n'écoute pas sur le réseau ; en cas d'instances multiples, il faut transmettre le hwnd pour cibler la bonne instance, sinon la cible est ambiguë.
  • Écritures locales : l'installation crée un venv en local et compile le DLL natif ; ce sont des modifications locales nécessaires.
  • Points non confirmés : les preuves officielles ne précisent pas si les outils offrent un mécanisme d'annulation, le détail des paramètres de chaque opération d'écriture, ni la compatibilité avec un Windows chinois/anglais ou d'autres versions de Python. L'absence de ces informations ne signifie pas l'absence de risque : sauvegardez votre projet avant toute opération d'écriture.