maya-mcp

Maya 2022 이상에서 쓰는 커스텀 MCP 서버. AI가 Maya를 직접 조작하게 해줍니다.

기존 오픈소스 서버들과 달리 툴을 수백 개 나열하지 않습니다. 코드 실행 + 자기탐색으로 전체 커버리지를 얻고, 구조화된 툴은 안전망에만 씁니다.

왜 이 구조인가

Maya 2022의 내장 Python은 3.7이고, 공식 mcp 파이썬 SDK는 3.10 이상을 요구합니다. 즉 MCP 서버 본체는 Maya 안에서 돌 수 없습니다. 그래서 두 조각으로 나뉩니다.

Claude ─(stdio)─> maya_mcp/           PC 파이썬 3.10+ / mcp SDK
                       │
                       │ TCP 127.0.0.1:20777
                       │ JSON-RPC 2.0 · 4바이트 길이 프리픽스
                       ▼
                  maya_mcp_bridge.py  Maya 2022 내부 / Python 3.7 / 표준 라이브러리만
                       │ executeInMainThreadWithResult
                       ▼
                    maya.cmds ← unreal_tools.py (L2 언리얼 파이프라인)

이 경계 덕분에 Maya를 2024/2026으로 올려도 브릿지 파일 하나만 확인하면 됩니다.

자매 프로젝트와의 정렬

unreal-mcp-bridge 와 규약을 맞췄습니다.

	공통
메시지	JSON-RPC 2.0 (method / params / result / error)
에러 코드	표준 (-32700 ~ -32603)
메서드명	<도메인>.<동작> 점 네임스페이스
구조	패키지 + tools/*.py + register_*_tools(mcp, conn)
스레드	워커 스레드 수신 → 메인/게임 스레드 디스패치

의도적으로 다른 것 하나 — 프레이밍. 저쪽은 개행 구분 + 64KB 제한, 이쪽은 4바이트 길이 프리픽스에 제한 없음입니다. Maya 는 씬 덤프처럼 큰 응답이 흔해 (cmds.ls() 한 번에도 64KB를 넘길 수 있습니다) 64KB 제한을 쓸 수 없습니다. 자세한 내용은 docs/PROTOCOL.md.

파일 구조

maya_mcp/              PC 쪽 (Python 3.10+)
  config.py            MMCP_* 환경변수
  connection.py        JSON-RPC 클라이언트
  server.py            서버 조립 (build_server)
  tools/               script · scene · inspection · viewport · unreal
maya_mcp_bridge.py     Maya 내부 (Python 3.7, 표준 라이브러리만)
unreal_tools.py        Maya 내부, 언리얼 파이프라인 구현
install_maya.py        Maya 쪽 원버튼 설치
server.py              엔트리 포인트 (기존 MCP 등록 경로 유지용)

툴 목록 (16개)

계층	툴	역할
L0	maya_execute	임의 Python 실행. 여기서 모든 기능이 나옵니다
L1	maya_search_commands	이름으로 maya.cmds 명령 검색
L1	maya_command_help	명령의 플래그·시그니처 조회
L3	maya_undo	직전 작업 되돌리기
L3	maya_viewport_capture	뷰포트를 이미지로 받아 결과 검증
—	maya_scene_info	단위·업축·프레임 범위·노드 개수
—	maya_ping	연결·버전 확인

L2 — 언리얼 파이프라인 (unreal_tools.py)

툴	성격	역할
maya_unreal_check	읽기 전용	프리즈·음수 스케일·히스토리·네이밍·UV·ngon·논매니폴드 감사
maya_unreal_check_skeleton	읽기 전용	조인트 오리엔트 편차, rotate 잔여값, 루트·좌우 네이밍 감사
maya_unreal_check_materials	읽기 전용	슬롯 수(=드로우 콜), 기본 머티리얼, 페이스 단위 할당, 미사용 SG
maya_unreal_prepare	변경	히스토리 삭제·프리즈·피벗·접두사 리네임 일괄
maya_unreal_cleanup_materials	변경	미사용 셰이딩 그룹 삭제, M_ 리네임
maya_unreal_make_lods	생성	LOD 메시 생성 + Maya LOD 그룹
maya_unreal_make_collision	생성	UBX_/USP_/UCP_/UCX_ 콜리전
maya_unreal_import_fbx	입력	FBX 를 Maya 로 가져오기 (언리얼 레벨 에셋 수신)
maya_unreal_export_fbx	출력	언리얼 프리셋 FBX

감사(읽기 전용)를 먼저 두는 구조입니다. 보지 않고 고치면 되돌릴 수 없는 문제 (뒤집힌 노멀 등)를 덮어쓰게 됩니다.

자동화하지 않기로 한 것들 — 판단이 필요하기 때문입니다:

• 음수 스케일 수정 — 프리즈해도 노멀이 뒤집힌 채 남습니다. 어느 면을 뒤집을지는 사람이 정합니다.
• 조인트 재오리엔트 — 이미 붙은 스킨 웨이트가 깨집니다. 감사만 합니다.
• 머티리얼 병합 — 어느 것을 남길지는 룩뎁 판단입니다.
• LOD 감소율 자동 결정 — 실루엣이 무너지는 지점은 에셋마다 다릅니다.

⚠️ UCX_ 컨벡스 콜리전 제약 — Maya 2022 에는 컨벡스 헐 명령이 없습니다 (런타임 조사로 확인). convex 옵션은 원본을 줄인 사본일 뿐 볼록함이 보장되지 않습니다. 대부분의 프롭은 box(UBX_)로 충분하고, 복잡한 형태는 언리얼 스태틱 메시 에디터의 Auto Convex Collision 을 쓰는 편이 낫습니다.

기존 서버 비교표에서 "Maya 2022에서는 undo와 뷰포트 캡처가 불가능"이라고 나오는 건 Maya의 한계가 아니라 그 서버들이 구현을 안 한 것뿐입니다. 둘 다 2022에서 잘 됩니다.

• undo — maya_execute 호출 하나를 undoInfo(openChunk/closeChunk) 로 묶습니다. AI가 무슨 짓을 하든 Ctrl+Z 한 번에 통째로 되돌아갑니다.
• 뷰포트 캡처 — playblast 로 PNG를 떠서 MCP 이미지로 돌려줍니다. AI가 자기 결과물을 보고 스스로 고칠 수 있게 되는 것이 자동화 품질을 가장 크게 가릅니다.

설치

1. Maya 쪽 (한 번만)

스크립트 에디터(Python 탭)에서 아래를 한 번 실행하면 끝입니다.

import sys; sys.path.append(r"C:\path\to\maya-mcp")
import install_maya; install_maya.install()

두 가지가 설치됩니다.

• 자동 시작 — ~/Documents/maya/scripts/userSetup.py 에 등록됩니다. 다음부터는 Maya 를 켜기만 하면 브릿지가 대기 상태가 됩니다.
• 셸프 버튼 — MCP 셸프에 원버튼 시작/중지 토글이 생깁니다. 셸프 탭이 많으면 맨 끝에 추가되니 탭 바를 오른쪽으로 넘겨서 찾으세요.

성공하면 출력창에 이렇게 찍힙니다:

[maya-mcp] 대기 중: 127.0.0.1:20777 (Maya 2022 / Python 3.7.7)

제거: import install_maya; install_maya.uninstall()

<details> <summary>설치 없이 수동으로 띄우기</summary>

import sys; sys.path.append(r"C:\path\to\maya-mcp")
import maya_mcp_bridge; maya_mcp_bridge.start()   # 중지는 stop()

플러그인 매니저에서 maya_mcp_bridge.py 를 로드해도 됩니다 (initializePlugin 이 start() 를 호출합니다). </details>

코드를 수정한 뒤에는 Maya 를 재시작하세요. importlib.reload 는 모듈 전역 (_server)을 초기화해 실행 중인 서버를 stop() 할 수 없게 만들고, 포트가 물린 채 start() 가 실패합니다. 셸프 버튼이 리로드를 하지 않는 이유이기도 합니다.

2. PC 쪽 (MCP 서버)

python -m venv .venv
.venv\Scripts\activate        # macOS/Linux: source .venv/bin/activate
pip install -e .              # 또는: pip install -r requirements.txt

pip install -e . 로 설치하면 maya-mcp 명령으로도 실행할 수 있습니다.

mcp 2.x(MCPServer)와 1.x(FastMCP) 양쪽을 지원합니다 — server.py 가 임포트 시점에 알아서 고릅니다. 2.0.0 에서 검증했습니다.

3. 클라이언트 등록

Claude Desktop / Claude Code 설정에 추가:

{
  "mcpServers": {
    "maya": {
      "command": "C:\\path\\to\\maya-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\maya-mcp\\server.py"]
    }
  }
}

Claude Code CLI 라면:

claude mcp add maya -- C:\path\to\maya-mcp\.venv\Scripts\python.exe C:\path\to\maya-mcp\server.py

언리얼 익스포트 워크플로

1. maya_unreal_check              지오메트리 문제 확인
2. maya_unreal_check_materials    슬롯 수 확인
3. maya_unreal_prepare            프리즈·히스토리·피벗·네이밍
4. maya_unreal_cleanup_materials  미사용 셰이딩 그룹 정리
5. maya_unreal_make_collision     UBX_ 콜리전 생성
6. maya_unreal_make_lods          LOD 생성
7. maya_viewport_capture          눈으로 검증          ← 건너뛰지 마세요
8. maya_unreal_export_fbx         콜리전·LOD 포함 익스포트

7번이 핵심입니다. LOD 검증 중에 실제로 겪은 사례: 삼각형 수 10.3% 유지, ngon 0, 논매니폴드 0 — 지표는 전부 정상이었는데 캡처해보니 실루엣이 눈에 띄게 깨져 있었습니다. 수치만으로 품질을 판단할 수 없습니다.

콜리전 메시는 원본과 같은 FBX 에 함께 익스포트해야 언리얼이 인식합니다.

언리얼과의 에셋 왕복

Maya 쪽 절반은 완성돼 검증까지 마쳤습니다.

방향	Maya 쪽	언리얼 쪽
Maya → 언리얼	maya_unreal_export_fbx ✅	asset.import_fbx ❌ 미구현
언리얼 → Maya	maya_unreal_import_fbx ✅	level.export_selected ❌ 미구현

FBX 왕복은 실기에서 좌표까지 보존되는 것을 확인했습니다(반지름 6.0 원형 배치를 내보냈다 되가져와 위치·삼각형 수 일치).

언리얼 쪽 커맨드 3개는 아직 없습니다. 자매 저장소 unreal-mcp-bridge 에 C++ 로 추가해야 하며, JSON-RPC 계약과 구현 메모를 docs/UNREAL_SIDE.md 에 정리해 뒀습니다. 그 문서의 코드는 빌드·검증되지 않았습니다.

그전까지는 사용자가 언리얼에서 직접 뽑아둔 FBX 를 maya_unreal_import_fbx 로 받는 방식으로 쓸 수 있습니다.

테스트

네 개의 스위트가 있고, 전부 통과 상태입니다 (Maya 2022.x + Python 3.12.10 + mcp 2.0.0 검증).

# 1. Maya 쪽 로직 (31개) — Maya 의 Python 3.7 에서 실제로 돌립니다
"C:\Program Files\Autodesk\Maya2022\bin\mayapy.exe" tests/test_bridge_mayapy.py

# 2. 서버 전송 계층 (25개) — 목 브릿지 상대. Maya 불필요
.venv\Scripts\python.exe tests/test_server_protocol.py

# 3. MCP 엔드투엔드 (6개) — 실제 MCP 클라이언트로 핸드셰이크·툴 호출. Maya 불필요
.venv\Scripts\python.exe tests/test_e2e_stdio.py

# 4. GUI 스모크 — Maya 를 띄우고 브릿지를 start() 한 상태에서 실행
.venv\Scripts\python.exe tests/smoke_gui.py

1번은 maya.standalone 배치 모드에서 _op_* 함수를 직접 호출합니다. 소켓 계층을 여기서 테스트하지 않는 이유는, 배치 모드에는 idle 이벤트 루프가 없어 executeInMainThreadWithResult 가 반환되지 않기 때문입니다. 프레이밍은 2번이 목 브릿지로 검증합니다. GUI 모드에서의 소켓 왕복과 뷰포트 캡처는 자동 테스트 범위 밖이므로, Maya 를 띄워서 직접 확인하세요.

환경 변수

변수	기본값	설명
MMCP_HOST	127.0.0.1	브릿지 호스트
MMCP_PORT	20777	브릿지 포트
MMCP_TIMEOUT	180	요청 타임아웃(초). 무거운 작업이 많으면 늘리세요

접두사는 unreal-mcp-bridge 의 UMCP_ 와 맞춘 것입니다. 예전 MAYA_MCP_* 도 계속 인식하지만 MMCP_* 가 우선합니다.

maya_execute 반환 규약

• 단일 표현식이면 그 값이 결과입니다 — cmds.ls(selection=True)
• 여러 줄이면 result 변수에 담긴 값이 결과입니다

objs = cmds.ls(type="mesh")
result = {"count": len(objs), "names": objs[:10]}

print 출력과 예외 트레이스백도 함께 돌아오므로, 실패하면 AI가 에러를 읽고 스스로 고칩니다.

보안 — 읽고 넘어가세요

이건 정의상 원격 코드 실행 통로입니다.

• 127.0.0.1 에만 바인딩합니다. HOST 를 0.0.0.0 으로 바꾸면 같은 네트워크의 누구나 여러분 Maya에서 임의 코드를 실행할 수 있습니다. 바꾸지 마세요.
• 렌더 노드, 공용 워크스테이션, 신뢰할 수 없는 네트워크에서는 켜지 마세요.
• 프로덕션 씬으로 먼저 시험하지 마세요. 사본으로 며칠 돌려보고 판단하세요.
• undo 청크가 있어도 여러 단계 작업을 완벽히 되돌린다는 보장은 없습니다. 작업 전에 저장하는 습관이 여전히 가장 확실한 안전망입니다.

알려진 제약

• 무거운 작업 중에는 Maya UI가 멈춥니다. maya.cmds 가 메인 스레드에서만 동작하므로 구조적으로 피할 수 없습니다. 타임아웃을 넉넉히 잡으세요.
• 배치 모드(maya -batch)에서는 뷰포트 캡처가 동작하지 않습니다.
• Maya의 undo 가 꺼져 있으면(undoInfo -state off) 되돌리기가 불가능합니다. maya_ping 이 undo_enabled 로 알려줍니다.

확장 방향

maya_execute 로 같은 코드를 반복해서 짜고 있다면, 그때 구조화 툴(L2)로 승격시키세요. 처음부터 툴을 많이 만드는 것이 가장 흔한 실패 패턴입니다. 승격 기준은 셋뿐입니다.

1. 파괴적이라 확인 게이트가 필요하다 (scene_new, delete_history)
2. 너무 자주 써서 매번 코드 짜는 게 낭비다 (create_primitive, set_attribute)
3. AI가 자주 틀린다 (스킨 바인드 옵션, UV 투영 파라미터)

라이선스

MIT