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 등록 경로 유지용)
| 계층 | 툴 | 역할 |
|---|---|---|
| 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 |
연결·버전 확인 |
| 툴 | 성격 | 역할 |
|---|---|---|
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가 자기 결과물을 보고 스스로 고칠 수 있게 되는 것이 자동화 품질을 가장 크게 가릅니다.
스크립트 에디터(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()
설치 없이 수동으로 띄우기
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() 를 호출합니다).
코드를 수정한 뒤에는 Maya 를 재시작하세요.
importlib.reload는 모듈 전역 (_server)을 초기화해 실행 중인 서버를stop()할 수 없게 만들고, 포트가 물린 채start()가 실패합니다. 셸프 버튼이 리로드를 하지 않는 이유이기도 합니다.
python -m venv .venv
.venv\Scripts\activate # macOS/Linux: source .venv/bin/activate
pip install -e . # 또는: pip install -r requirements.txtpip install -e . 로 설치하면 maya-mcp 명령으로도 실행할 수 있습니다.
mcp 2.x(MCPServer)와 1.x(FastMCP) 양쪽을 지원합니다 — server.py 가 임포트
시점에 알아서 고릅니다. 2.0.0 에서 검증했습니다.
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.py1. 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.py1번은 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_* 가 우선합니다.
- 단일 표현식이면 그 값이 결과입니다 —
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)로 승격시키세요.
처음부터 툴을 많이 만드는 것이 가장 흔한 실패 패턴입니다. 승격 기준은 셋뿐입니다.
- 파괴적이라 확인 게이트가 필요하다 (
scene_new,delete_history) - 너무 자주 써서 매번 코드 짜는 게 낭비다 (
create_primitive,set_attribute) - AI가 자주 틀린다 (스킨 바인드 옵션, UV 투영 파라미터)
MIT