mmd-mcp: controle o MikuMikuDance e configure o MME via MCP no Windows

mmd-mcp é um servidor MCP stdio voltado ao Windows para controlar operações autoriais no MikuMikuDance (MMD) e a configuração de efeitos MME. Os pré-requisitos para que ele seja adequado são claros: você precisa estar no Windows, já ter iniciado por conta própria o MMD 9.32 x64 (a edição japonesa — o servidor recusa versões não suportadas) e estar disposto a concluir uma instalação compilando a partir do código-fonte (requer Python x64 e o componente "Desenvolvimento para desktop com C++" do Visual Studio 2022/Build Tools). Ele não inicia o MMD automaticamente e não escuta na rede. Se o seu ambiente não atender a essas condições, ou se você não quiser mexer na cadeia de ferramentas de compilação, ele não é a melhor escolha.

Para quem é adequado

• Pessoas que fazem animações MMD no Windows e precisam ajustar modelos, câmera, luzes, física e timeline de forma programática, ou editar a atribuição de efeitos EMM do MME e exportar vídeo AVI.
• O ambiente validado é MMD 9.32 x64 na edição japonesa, Windows japonês e Python 3.10 x64; outras versões do MMD são recusadas, então usuários de outras versões devem se considerar não suportados.
• Não é adequado para: usuários de macOS/Linux, quem ainda não instalou o MMD ou usa versões não validadas, e quem não quer instalar os componentes C++ do Visual Studio. As evidências oficiais não mencionam suporte a macOS/Linux — isso permanece desconhecido.

Primeira tentativa em 3 minutos

Atenção: este caminho principal não é algo que se conclui em 3 minutos — compilar a DLL a partir do código-fonte leva um tempo considerável; o "3 minutos" refere-se à pequena quantidade de passos.

Pré-requisitos:

1. Ambiente Windows com Python x64 instalado (ambiente validado: 3.10 x64).
2. Visual Studio 2022 ou Build Tools instalados, com o componente "Desenvolvimento para desktop com C++" marcado (usado para compilar a DLL nativa).
3. MMD 9.32 x64 na edição japonesa já iniciado — o servidor não inicia o MMD automaticamente.

Instalação (no diretório do repositório, comandos PowerShell oficiais):

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

O terceiro comando compila a DLL nativa; é uma etapa obrigatória e o artefato compilado fica localmente.

Registro no cliente MCP (via stdio), configuração de exemplo oficial:

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

O caminho deve ser substituído pela localização do seu próprio venv.

Para a primeira chamada, recomenda-se usar mmd_list_windows: ela apenas lista as janelas, sem alterar a cena, sendo a chamada inicial de menor risco. O sinal de sucesso é receber a lista das janelas do MMD atual e seus hwnd. Se você tiver várias instâncias do MMD abertas, cada chamada subsequente precisará passar o hwnd retornado por mmd_list_windows. As evidências oficiais não indicam se mmd_list_windows é marcado com readOnlyHint; não trate nenhuma ferramenta como de risco zero.

Outros métodos de instalação: oficialmente, apenas o caminho de instalação a partir do código-fonte acima é fornecido; não há instruções para pacote pip nem binários pré-compilados.

Casos de uso

Caso 1: verificar a conexão e gerenciar múltiplas instâncias. Cenário: você acabou de configurar o cliente e quer confirmar que ele encontra o MMD. Chame mmd_list_windows e observe a lista de janelas retornada e os hwnd. Se houver apenas um MMD aberto, você pode chamar as outras ferramentas diretamente depois; se houver vários, passe o hwnd correspondente em cada chamada para especificar o alvo, conforme a documentação oficial. Você pode confirmar até aqui: a enumeração de janelas e o mecanismo de passagem de hwnd; para formatos de saída mais detalhados, considere o que for retornado de fato.

Caso 2: escrever keyframes de câmera em lote e exportar vídeo. Cenário: você terminou uma animação e quer definir programaticamente os movimentos de câmera e exportar para AVI. A versão oficial v0.3.0 oferece 50 ferramentas; entre elas, mmd_batch_camera_keys escreve keyframes de câmera em lote e mmd_export_video exporta para AVI. Atenção: ambas são operações de escrita sobre o projeto MMD atualmente aberto: a escrita de keyframes e a exportação de vídeo alteram/geram conteúdo do projeto; antes de chamá-las, confirme que o projeto aberto pode ser modificado ou que já existe um backup. As evidências oficiais não indicam se essas ferramentas têm caminho de desfazer, nem detalham os parâmetros de exportação; antes de chamar, verifique as definições de parâmetros no seu cliente.

Limites de uso

• Natureza de leitura e escrita: das 50 ferramentas, há tanto chamadas de consulta de janela/cena quanto operações de escrita, como seleção de modelos, escrita em lote de keyframes de ossos/câmera, leitura e escrita de atribuição de efeitos EMM (mmd_read_effect_assignments / mmd_write_effect_assignments) e exportação AVI. As operações de escrita atuam diretamente no projeto MMD que você já tem aberto.
• Ligação ao ambiente: o ambiente validado se restringe ao MMD 9.32 x64 (edição japonesa, com verificação oficial por um SHA-256 específico); builds não suportados são recusados.
• Pré-requisitos e efeitos colaterais: o MMD deve ser iniciado manualmente antes; o servidor não inicia o MMD automaticamente e não escuta na rede; com múltiplas instâncias, é obrigatório passar o hwnd para especificar o alvo, caso contrário o alvo fica ambíguo.
• Escritas locais: a instalação cria um venv local e compila a DLL nativa — são modificações locais necessárias.
• Itens não confirmados: as evidências oficiais não esclarecem se as ferramentas oferecem mecanismo de desfazer, os detalhes de parâmetros de cada operação de escrita, nem a compatibilidade com Windows em chinês/inglês ou outras versões do Python. A ausência dessas informações não significa ausência de risco; faça backup do projeto por conta própria antes de usar operações de escrita.