mmd-mcp: controla MikuMikuDance y configura MME con MCP en Windows

mmd-mcp es un servidor MCP por stdio orientado a Windows, para controlar operaciones de MikuMikuDance (MMD) y la configuración de efectos de MME. Sus requisitos previos son claros: debes estar en Windows, haber iniciado tú mismo MMD 9.32 x64 (la versión de distribución japonesa; el servidor rechaza las versiones no compatibles) y estar dispuesto a compilar e instalar desde el código fuente (requiere Python x64 y el componente «Desarrollo de escritorio con C++» de Visual Studio 2022/Build Tools). No inicia MMD automáticamente ni escucha en la red. Si tu entorno no cumple estas condiciones, o no quieres usar la cadena de herramientas de compilación, no es una buena primera opción.

Para quién es

• Personas que hacen animación con MMD en Windows y necesitan ajustar modelos, cámara, iluminación, física y línea de tiempo de forma programática, o editar la asignación de efectos EMM de MME y exportar video AVI.
• Entorno verificado: MMD 9.32 x64 de distribución japonesa, Windows en japonés y Python 3.10 x64; se rechazan otras versiones de MMD, por lo que los usuarios de otras versiones deben considerarlas no compatibles.
• No es adecuado para: usuarios de macOS/Linux, personas que aún no tienen MMD instalado o usan una versión no verificada, y quienes no quieran instalar los componentes C++ de Visual Studio. La evidencia oficial no menciona soporte para macOS/Linux; esto es desconocido.

Primer intento en 3 minutos

Nota: este camino principal no se completa en 3 minutos; compilar la DLL desde el código fuente lleva bastante tiempo. «3 minutos» se refiere a la cantidad reducida de pasos.

Requisitos previos:

1. Entorno Windows con Python x64 instalado (entorno verificado: 3.10 x64).
2. Visual Studio 2022 o Build Tools instalado, con el componente «Desarrollo de escritorio con C++» (para compilar la DLL nativa).
3. MMD 9.32 x64 en japonés ya iniciado: el servidor no inicia MMD automáticamente.

Instalación (en el directorio del repositorio, comandos oficiales de PowerShell):

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

El tercer comando compila la DLL nativa; es un paso obligatorio y el resultado de la compilación se genera localmente.

Registro en el cliente MCP (vía stdio), configuración de ejemplo oficial:

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

Debes reemplazar la ruta por la ubicación de tu propio venv.

Para la primera llamada se recomienda mmd_list_windows: solo enumera ventanas, no modifica la escena y es la primera llamada de menor riesgo. La señal de éxito es que devuelva la lista de ventanas actuales de MMD con sus hwnd. Si tienes varias instancias de MMD iniciadas, cada llamada posterior necesitará pasar el hwnd devuelto por mmd_list_windows. La evidencia oficial no indica si mmd_list_windows está marcado como de solo lectura (readOnlyHint); no consideres ninguna herramienta como de riesgo cero.

Otros métodos de instalación: la evidencia oficial solo ofrece la vía de instalación desde código fuente descrita; no hay instrucciones para un paquete pip ni binarios precompilados.

Casos de uso

Caso 1: verificar la conexión y gestionar múltiples instancias. Situación: acabas de configurar el cliente y quieres confirmar que encuentra MMD. Llama a mmd_list_windows y observa la lista de ventanas y los hwnd devueltos. Si solo hay una instancia de MMD, después puedes llamar directamente a otras herramientas; si hay varias, pasa el hwnd correspondiente en cada llamada para indicar el objetivo, según la documentación oficial. Puedes confirmar hasta aquí: la enumeración de ventanas y el mecanismo de paso de hwnd; para los detalles del formato de salida, guíate por la respuesta real.

Caso 2: escribir lotes de keyframes de cámara y exportar video. Situación: terminaste una animación y quieres configurar la cámara programáticamente y exportar a AVI. La versión oficial v0.3.0 ofrece 50 herramientas; entre ellas, mmd_batch_camera_keys permite escribir lotes de keyframes de cámara y mmd_export_video exporta a AVI. Ten en cuenta que ambas son operaciones de escritura sobre el proyecto MMD actual: escribir keyframes y exportar video modifican o generan contenido del proyecto, así que antes de llamarlas confirma que el proyecto abierto puede modificarse o que ya tienes una copia de seguridad. La evidencia oficial no indica si estas herramientas ofrecen una vía de deshacer, ni detalla los parámetros de exportación; revisa las definiciones concretas de parámetros en tu cliente antes de llamarlas.

Límites de uso

• Naturaleza de lectura/escritura: de las 50 herramientas, hay llamadas de consulta de ventanas/escena, pero también operaciones de escritura como selección de modelos, escritura en lote de keyframes de huesos y cámara, lectura y escritura de asignaciones de efectos EMM (mmd_read_effect_assignments / mmd_write_effect_assignments) y exportación a AVI. Las operaciones de escritura actúan directamente sobre el proyecto MMD que tienes abierto.
• Vinculación al entorno: el entorno verificado se limita a MMD 9.32 x64 (distribución japonesa, verificada oficialmente por un SHA-256 específico); las compilaciones no compatibles se rechazan.
• Requisitos previos y efectos secundarios: debes iniciar MMD manualmente de antemano; el servidor no inicia MMD automáticamente ni escucha en la red; con múltiples instancias debes pasar el hwnd para indicar el objetivo; de lo contrario, el objetivo no queda claro.
• Escrituras locales: la instalación crea un venv local y compila la DLL nativa; son cambios locales necesarios.
• Puntos sin confirmar: la evidencia oficial no indica si las herramientas ofrecen mecanismo de deshacer, los detalles de parámetros de cada operación de escritura, ni la compatibilidad con Windows en chino/inglés u otras versiones de Python. La ausencia de esta información no implica ausencia de riesgo; haz copias de seguridad del proyecto por tu cuenta antes de usar operaciones de escritura.