MayaBridge

MayaBridge is a lightweight MCP-style bridge for Autodesk Maya. It lets Codex, Claude Code, or another local agent execute Python inside a running Maya session through a TCP bridge with automatic UDP discovery and endpoint cache fallback.

Layout

• py/ - in-Maya server and helper API.
• py/maya_fps_helpers.py - FPS weapon rig, attach-point, IK target, and keyframe helper API.
• scripts/bridge.py - external CLI used by agents.
• scripts/start_bridge.py - load this in Maya to start the server manually.
• .claude/skills/maya-bridge/ - Claude/Codex skill instructions.
• tools/install_maya_startup.ps1 - installs Maya userSetup.py autostart.
• tools/install_agent_skill.ps1 - copies the skill into .claude and .codex.

Quick Start

Manual start inside Maya Script Editor, Python tab:

exec(open(r"D:/LAFAN/MayaBridge/scripts/start_bridge.py").read())

Then from PowerShell:

cd D:\LAFAN\MayaBridge
python scripts\bridge.py ping
python scripts\bridge.py exec "from maya_helpers import get_scene_info, dump_json; dump_json(get_scene_info())"
python scripts\bridge.py exec-file scripts\example.py

FPS Animation Helpers

Common agent entrypoints:

python scripts\bridge.py exec "from maya_fps_helpers import detect_weapon_roots, dump_json; dump_json(detect_weapon_roots()[:10])"
python scripts\bridge.py exec "from maya_fps_helpers import identify_weapon_skeleton, dump_json; dump_json(identify_weapon_skeleton())"
python scripts\bridge.py exec "from maya_fps_helpers import suggest_hand_ik_targets, dump_json; dump_json(suggest_hand_ik_targets(weapon_type='assault_rifle'))"

Available FPS helpers:

• detect_weapon_roots() - score likely weapon roots by name and descendants.
• identify_weapon_skeleton(root) - classify common weapon joints such as mag, bolt, trigger, barrel, sight, stock, and grip.
• infer_weapon_attach_points(root) - infer grip, support grip, muzzle, magazine, bolt, and sight transforms.
• suggest_hand_ik_targets(root, character_root, weapon_type) - suggest right/left hand IK target transforms.
• create_ik_target_locators(...) - create scene locators for suggested IK targets.
• read_keyframes(...), write_keyframes(...), offset_keyframes(...) - batch keyframe/curve IO for animation editing.
• analyze_weapon_animation(...) - summarize keyed weapon-part motion.
• generate_aim_offset_preview(...) - generate yaw/pitch pose suggestions without applying them.

Autostart

Install into Maya's userSetup.py:

powershell -NoProfile -ExecutionPolicy Bypass -File tools\install_maya_startup.ps1 -MayaVersion 2024

Restart Maya. The bridge should print:

[MayaBridge] listening on 127.0.0.1:<port>
[MayaBridge] discovery on 239.255.44.44:9017

Agent Skill

Install the skill:

powershell -NoProfile -ExecutionPolicy Bypass -File tools\install_agent_skill.ps1

In Claude Code:

使用 maya-bridge，ping 当前 Maya

The skill should run its bundled scripts/bridge.py; it should not ask for the printed port unless both discovery and endpoint cache fallback fail.

Safety

Agent scripts can inspect scenes freely. Destructive operations such as deleting nodes, overwriting files, or saving scenes should require explicit user confirmation.