MCP

mmd-mcp: Windows에서 MCP로 MikuMikuDance 제작 및 MME 설정하기

mmd-mcp는 Windows에서 MikuMikuDance를 프로그래밍 방식으로 조작해 애니메이션과 MME 특수 효과 설정을 하기에 가장 적합하지만, 일본어판 MMD 9.32 x64를 먼저 직접 실행하고 Visual Studio C++ 구성 요소가 필요한 소스 컴파일 설치를 완료해야 합니다.

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는 Windows용 stdio MCP 서버로, MikuMikuDance(MMD)의 저작 작업과 MME 특수 효과 설정을 제어하는 데 사용됩니다. 적합한 전제 조건은 분명합니다. Windows를 사용 중이어야 하고, 일본어 배포판인 MMD 9.32 x64를 직접 실행한 상태여야 하며(서버는 지원하지 않는 버전을 거부합니다), 소스 코드 컴파일 설치를 완료할 의향이 있어야 합니다(Python x64와 Visual Studio 2022/Build Tools의 C++ 데스크톱 개발 구성 요소가 필요합니다). 이 서버는 MMD를 자동으로 시작하지 않고 네트워크도 리슨(listen)하지 않습니다. 환경이 이 조건들을 충족하지 않거나 컴파일 도구 체인을 다루고 싶지 않다면 첫 선택으로 적합하지 않습니다.

적합한 사용자

  • Windows에서 MMD 애니메이션 제작을 하는 사람으로, 모델, 카메라, 조명, 물리, 타임라인을 프로그래밍 방식으로 조정하거나, MME의 EMM 특수 효과 할당을 편집하거나, AVI 영상을 출력해야 하는 사람.
  • 검증 환경은 일본어 배포판 MMD 9.32 x64, 일본어 Windows, Python 3.10 x64입니다. 다른 MMD 버전은 거부되므로, 다른 버전 사용자는 지원되지 않는 것으로 간주해야 합니다.
  • 부적합: macOS/Linux 사용자, MMD를 아직 설치하지 않았거나 검증되지 않은 버전을 사용하는 사람, Visual Studio C++ 구성 요소를 설치하고 싶지 않은 사람. 공식 자료는 macOS/Linux 지원을 언급하지 않으며, 이는 미지수입니다.

3분 만에 첫 시도 완료하기

주의: 이 메인 경로는 3분 안에 끝나는 것이 아닙니다. 소스에서 네이티브 DLL을 컴파일하는 데 상당한 시간이 걸립니다. "3분"은 단계 수가 적다는 의미입니다.

전제 조건:

  1. Windows 환경, Python x64 설치됨(검증 환경은 3.10 x64).
  2. Visual Studio 2022 또는 Build Tools 설치 및 C++ 데스크톱 개발 구성 요소 선택(네이티브 DLL 컴파일용).
  3. 일본어판 MMD 9.32 x64 실행 중 — 서버는 MMD를 자동으로 시작하지 않습니다.

설치(저장소 디렉터리에서, 공식 제공 PowerShell 명령):

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

세 번째 명령이 네이티브 DLL을 컴파일하며, 이는 필수 단계입니다. 컴파일 결과물은 로컬에 생성됩니다.

MCP 클라이언트에 등록(stdio 방식), 공식 예시 설정:

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

경로는 자신의 venv 위치로 교체해야 합니다.

첫 호출로는 mmd_list_windows를 권장합니다. 창만 나열할 뿐 씬을 변경하지 않아 가장 위험도가 낮은 첫 호출입니다. 성공 신호는 현재 MMD 창 목록과 그 hwnd가 반환되는 것입니다. MMD 인스턴스를 여러 개 실행했다면, 이후 모든 호출에서 mmd_list_windows가 반환한 hwnd를 전달해야 합니다. 공식 자료는 mmd_list_windows에 readOnlyHint가 표시되어 있는지 명시하지 않으므로, 어떤 도구도 무위험으로 간주하지 마십시오.

다른 설치 방법: 공식 문서는 위 소스 설치 경로만 제공하며, pip 설치 패키지나 사전 컴파일된 바이너리에 대한 안내는 없습니다.

사용 사례

사례 1: 연결 확인 및 다중 인스턴스 관리. 상황: 클라이언트를 방금 설정했고 MMD를 찾을 수 있는지 확인하고 싶습니다. mmd_list_windows를 호출하고 반환된 창 목록과 hwnd를 확인합니다. MMD가 하나만 실행 중이면 이후 다른 도구를 바로 호출할 수 있고, 여러 개를 실행했다면 공식 설명대로 각 호출에 해당 hwnd를 전달해 대상을 지정합니다. 여기까지 확인 가능: 창 열거와 hwnd 전달 메커니즘. 더 세부적인 출력 형식은 실제 반환값을 기준으로 합니다.

사례 2: 카메라 키프레임 일괄 작성 및 영상 출력. 상황: 모션을 만들었고 카메라 워크를 프로그래밍 방식으로 설정하고 AVI로 출력하고 싶습니다. 공식 v0.3.0은 50개의 도구를 제공하며, 그중 mmd_batch_camera_keys는 카메라 키프레임을 일괄 작성하고, mmd_export_video는 AVI를 출력합니다. 두 도구 모두 현재 MMD 프로젝트에 대한 쓰기 작업입니다. 키프레임 작성과 영상 출력은 프로젝트 내용을 변경/생성하므로, 호출 전에 현재 열려 있는 프로젝트가 수정 가능한지 또는 백업이 있는지 확인하십시오. 공식 자료는 이러한 도구에 실행 취소 경로가 있는지, 출력 파라미터 세부 사항을 명시하지 않으므로, 호출 전에 클라이언트에서 구체적인 파라미터 정의를 확인하십시오.

사용 경계

  • 읽기/쓰기 성격: 50개 도구 중에는 창/씬 조회류 호출도 있고, 모델 선택, 뼈대/카메라 키프레임 일괄 작성, EMM 특수 효과 할당 읽기/쓰기(mmd_read_effect_assignments / mmd_write_effect_assignments), AVI 출력 등 쓰기 작업도 있습니다. 쓰기 작업은 이미 열어 둔 MMD 프로젝트에 직접 적용됩니다.
  • 환경 제약: 검증 환경은 MMD 9.32 x64(일본어 배포판, 공식이 특정 SHA-256으로 검증)로 한정되며, 지원하지 않는 빌드는 거부됩니다.
  • 전제 조건과 부작용: MMD를 미리 수동으로 실행해야 합니다. 서버는 MMD를 자동 시작하지 않고 네트워크도 리슨하지 않습니다. 다중 인스턴스 시 hwnd를 전달해 대상을 지정해야 하며, 그렇지 않으면 대상이 불분명합니다.
  • 로컬 쓰기: 설치 과정에서 로컬에 venv를 생성하고 네이티브 DLL을 컴파일하며, 이는 필수적인 로컬 변경입니다.
  • 미확인 사항: 공식 자료는 도구에 실행 취소 메커니즘이 있는지, 각 쓰기 작업의 파라미터 세부 사항, 중국어/영어 Windows 또는 다른 Python 버전과의 호환성을 명시하지 않습니다. 이 정보가 없다는 것이 위험이 없다는 뜻은 아니며, 쓰기 작업을 사용하기 전에 스스로 프로젝트를 백업하십시오.