mcp-for-maya

English | 简体中文

mcp-for-maya

AI エージェントに Autodesk Maya シーンの空間認識を提供する MCP サーバー

これは何ですか

mcp-for-maya は、LLM エージェント（Codex、Claude など）が Autodesk Maya を直接操作して、3D モデリング、シーン計画、エンジニアリング品質の成果物作成を行えるようにする Model Context Protocol (MCP) サーバーです。

chadrik/maya-mcp-server からフォークされ、上流の接続スタックの上に、空間認識、決定論的な監査、トランザクションの安全性、ビジュアルループからなるシーンインテリジェンスレイヤーを追加しています。

主な機能： エージェントはもう「見ずに書く」ことはありません。空間状態、マテリアル、オブジェクト間の関係を認識し、エンジニアリングルールに照らして変更を検証できます。

警告

このサーバーは Maya 内で任意の Python を実行します。これは設計された機能であり、バグではありません。組み込みの検証／レート制限／監査パイプラインは、事故や注入された指示に対する安全策であり、悪意のあるクライアントに対する防壁ではありません。接続されたエージェントは信頼されているものとして扱います。docs/threat-model.md をご覧ください。

以下のアセットはすべて、このプロジェクト独自のツールチェーンで実際にキャプチャしたものです。モックアップはありません。シーンは execute_code / write_module（およびライブの asset_import 1 回）を使ってプロシージャルに構築し、フレームは scene_render_preview でレンダリングしました。監査ペアは scene_review と scene_viewport_snapshot で作成し、オービットシーケンスは Maya 2024 の GUI セッションで playblast を使ってフレームごとにキャプチャしました。

プロンプト	結果
write_module → t20_movement.build() — 「パラメトリックなインボリュート歯車列のムーブメント：正確なインボリュート歯、ジュネーブ模様のプレート、青焼きネジ、ルビーの石、らせん状ヒゲゼンマイ」
write_module → t20_bonsai.build() — 「ローポリのLシステム盆栽：再帰的な枝分かれ、面取りされた葉のパッド、鉢＋苔＋石」
asset_import("vintage_pocket_watch") + asset_import("metal_tool_chest") → t20_workbench.build() — 「時計職人の作業台：テクスチャを接続したインポート済みアセット、プロシージャルなインボリュート歯車の予備部品」
write_module → t20_street.build() — 「ローポリの街角区画：11棟のパラメトリック建物、切妻屋根、日よけ、街路設備、駐車中のバン」
write_module → t20_teapot.build() — 「ユタ・ティーポットの再現：回転プロファイルの本体、ベジェ曲線のテーパー付き注ぎ口、耳型の取っ手、市松模様の床」
がらくたが散乱した作業台で scene_review() を実行 → scene_plan(auto_fix=True) とクリーンアップ → 再度 scene_review() を実行 — スコア 53.7 → 64.2

.github/assets-src/ のスクリプトで、すべてのフレームを再現できます。

blender-mcp との比較

ahujasid/mcp-for-blender との、率直な3段階比較です（2026-09測定）。

段階	内容
このプロジェクト独自	ICEVで強制されるワークフロー（サーバーの指示に記載）、CoS表記の出力、チェックポイント／ロールバックによるトランザクション安全性、scene_planによる包括的なプランニング（ゾーンのマッピング＋レイアウトの提案）、複数セッションの管理、決定論的な監査チェック11項目、メタデータ付きプレイブラストのレンダープレビュー
blender-mcp独自	アセットエコシステムの幅広さ（Sketchfab／Hyper3D／Hunyuan3D）、オブジェクトのCRUDを第一級で扱うツール、AI生成モデルとの連携、コミュニティの規模
共通	MCPツールの提供範囲、Poly Havenのアセットソース、ビューポートのスクリーンショットによるフィードバック、任意のPython実行、ローカルソケット接続

Poly Havenのモデル検索＋インポートは0.2.0でリリースされました（issue #2の最小実装：FBX＋テクスチャ接続。HDRIとテクスチャパックは今後のロードマップに残っています）。AI生成とオブジェクトのCRUDを第一級で扱う機能は、明示的に対象外です。後者はすでに execute_code で対応しています。 共有アセットのダウンロード経路では、このプロジェクトの制御は一般的な方法ではなく、コードによって適用されます。ダウンロードはホスト側のみで行われます（HTTPS ＋ ホストの許可リスト、ファイルごとの md5、サイズ上限、URL の最後のセグメントからファイル名をサニタイズ（polyhaven.py））。Maya 自体がネットワークにアクセスすることはありません。適用の詳細：docs/threat-model.md。

機能	ツール	備考
🧊 空間認識	scene_snapshot scene_inspect scene_measure	1 回の呼び出しでシーン全体の空間モデルを取得。距離／重なり／隙間を正確に測定
🎨 美的分析	scene_aesthetics	5 つの観点：色彩理論（60-30-10）、空間構成（黄金比／三分割法）、比率とスケール（人間工学）、ライティング品質（三点照明／フィル比／色温度／減衰）、視覚的な流れ
🎬 カメラプランニング	camera_create camera_orbit	業界標準の 8 種類のショットタイプ ＋ 周回アニメーション
🛡️ 災害復旧	scene_checkpoint scene_rollback scene_checkpoint_list	exportAll のインメモリスナップショット。ロールバック時に元のパスを明示的に再バインド
🧠 シーンプランニング	scene_plan	構成の健全性、ゾーンのバランス、レイアウトの提案、競合の防止、自然言語によるプランニング
📋 エンジニアリング監査	scene_review scene_validate scene_assert	11 項目の決定論的チェック（0～100 点）＋ カスタム制約の検証 ＋ 状態アサーション
⚡ コード実行	execute_code write_module	Maya で任意の Python を実行／再利用可能なモジュールを注入
👁️ ビジュアルループ	scene_viewport_snapshot scene_render_preview	WYSIWYG ビューポートのキャプチャ ＋ 1 フレームのプレイブラストプレビュー（GUI セッションのみ）
🔌 セッション管理	list_sessions add_session maya_setup_guide	複数セッションの検出／接続 ＋ 接続診断／インストール／フォールバックのガイダンス
📦 アセットライブラリ	asset_search asset_import	Poly Haven の CC0 モデル — ホスト側で HTTPS ダウンロード（ホストの許可リスト、md5 検証、サイズ上限、platformdirs キャッシュ）、Maya 側で FBX をインポートしてテクスチャを接続、ポリゴン数／寸法のガード、GRP_asset_<id> による重複排除
📤 シーンのエクスポート	scene_export	FBX／OBJ／USD エクスポート — シーン全体または名前付きオブジェクト。形式は拡張子から推定（競合はエラーとし、推測しません）、親ディレクトリは自動作成、上書きはオプトイン、選択状態を復元
🔎 シーングラフのイントロスペクション	scene_describe scene_nodes	API レベルでノードを自己記述（正確な型、属性ごとのメタデータ：keyable／connectable／enum／範囲、接続情報 — サイズ上限あり、*_truncated で切り詰めを明示、limit は最大 1000）＋ DAG 以外のノード（マテリアル／ツールノードを含む）も列挙し、has_more／next_cursor によるページネーションに対応

MCP ツールは合計 25 個です。

1. インストール

# Install from PyPI (recommended)
pip install mcp-for-maya

# or run straight away with uvx
uvx mcp-for-maya

# alternative: install from git with uv
uv tool install git+https://github.com/Xxx91n/mcp-for-maya.git

# or clone the source
git clone https://github.com/Xxx91n/mcp-for-maya.git
cd mcp-for-maya
pip install -e .

メモ

3 層の命名：dist 名 mcp-for-maya（PyPI のパッケージ名）→ インポート用パッケージ maya_mcp_server をインストール（upstream から引き継いだ名前）。スクリプト名は mcp-for-maya（旧名 maya-mcp-server も互換エイリアスとして維持）。コマンド名が dist 名と一致するため、uvx mcp-for-maya は正確に解決されます。

2. Maya に接続

オプション A：自動（推奨）

MCP サーバーの実行中に、エージェントが maya_setup_guide を呼び出して接続手順を進めます。

1. Maya が起動していることを確認します
2. エージェントに任意の指示を出します（例：「Maya のシーンを見て」）
3. 未接続の場合、エージェントが診断を実行し、userSetup.py をインストールできます（マーカーブロックを冪等にマージし、書き込み前にタイムスタンプ付きのバックアップを作成）
4. Maya を再起動すると、コマンドポートが自動的に開きます

オプション B：手動

Maya のスクリプトエディタ（MEL ではなく Python モード）で：

import maya.cmds as cmds

cmds.commandPort(name=":7001", sourceType="python")

オプション C：永続的な自動接続

userSetup.py として Maya のスクリプトディレクトリに保存します。

プラットフォーム	パス
Windows	%MAYA_APP_DIR%\<version>\scripts\
Linux	~/maya/<version>/scripts/
macOS	~/Library/Preferences/Autodesk/maya/<version>/scripts/

import maya.cmds as cmds

cmds.evalDeferred('cmds.commandPort(name=":7001", sourceType="python")', lowestPriority=True)

複数の Maya インスタンス

commandPort は、1 つの host:port にバインドされる単一のリスニングソケットです。2 つ目のインスタンスは同じポートへのバインドに失敗するため、Maya インスタンスごとに独自のポートが必要です。一般的な構成は次のとおりです。

Maya インスタンス	commandPort	備考
インスタンス A	:7001 python	プライマリ
インスタンス B	:7002 python	2 つ目のインスタンス
インスタンス A	:7011 mel	MEL ポート（自動検出され、除外されるため、エラーが大量に出ることはありません）

各インスタンス内（Script Editor または独自の userSetup.py）で cmds.commandPort(name=":<port>", sourceType="python") を実行します。主な方法は自動スキャンです。サーバーは Maya のリスニングポートを定期的に列挙して起動します。セッションを検出できなかった場合は、add_session(host, port) を手動で実行します。スキャンでコンピューター上の Maya 以外の TCP サービスをプローブする場合は、MAYA_MCP_INCLUDE_PORTS=7001,7002（カンマ区切り。7005-7010 の範囲指定も可能）でプローブ対象を限定するか、MAYA_MCP_EXCLUDE_PORTS=<port> で対象外のポートを指定してください。

注：commandPort はセッションをまたいで保持されません。Maya の終了とともに閉じます。永続化するには、userSetup.py に記述してください（オプション C）。

トラブルシューティング

問題	対処方法
list_sessions の結果が空	maya_setup_guide(action="diagnose") を呼び出してください
ポートが使用中	他の Maya インスタンスを閉じるか、別のポートを選んでください
userSetup.py が読み込まれない	正しいスクリプトディレクトリにあることを確認し、Maya を再起動してください
ファイアウォールによるブロック	localhost:7001 に接続できることを確認してください
2 つ目の Maya インスタンスが一覧に表示されない	インスタンスごとに独自の commandPort が必要です（同じポートではバインドが競合します）。スキャンで検出されない場合は、add_session(host, port) を呼び出してください
Script Editor に構文エラーが大量に表示される	MEL ポートをプローブしていることを示す以前の症状です。現行バージョンでは Python 以外のポートは自動的に除外されます。解消しない場合は、MAYA_MCP_EXCLUDE_PORTS でそのポートを対象外にしてください

3. MCP クライアントを設定する

Codex の ~/.codex/config.toml：

[mcp_servers.maya]
command = "uvx"
args = ["mcp-for-maya"]
tool_timeout_sec = 120

git ソースの場合は args = ["--from", "git+https://github.com/Xxx91n/mcp-for-maya.git", "mcp-for-maya"] を使用します。ソースチェックアウトの場合は command = "python"、args = ["-m", "maya_mcp_server"] を使用し、env の下で PYTHONPATH に <repo>/src を指定します。

4. 使用する

自然な言葉で話しかけます。

「Maya シーンに何があるか確認して、入口にディスプレイ棚を作成してください」

エージェントは scene_snapshot() を呼び出し、シーンを理解してモデリングした後、scene_review() で結果を監査します。

すべてのシーン変更は ICEV ループに従います（エージェントのプロセスカードとしても同梱されています。skills/icev-workflow を参照）。

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ INSPECT  │ ──→ │ COMPUTE  │ ──→ │ EXECUTE  │ ──→ │ VERIFY   │
│ snapshot │     │  plan    │     │  apply   │     │  audit   │
└──────────┘     └──────────┘     └──────────┘     └──────────┘

1. INSPECT：scene_snapshot() でシーン全体の空間データを取得します
2. COMPUTE：そのデータに基づいて位置、サイズ、クリアランスを計画します
3. EXECUTE：execute_code() で Maya Python を適用します
4. VERIFY：scene_assert() と scene_review() で結果を確認します。GUI セッションでは、ビジュアルツールによりピクセルレベルで確認できます

ツールリファレンス

空間

scene_snapshot(detail="compact", format="cos")  # full scene in one call
scene_inspect(target="wall_entrance", include_neighbors=True)
scene_measure(obj_a="wall_north", obj_b="counter_A", mode="clearance")
scene_assert(expectations='{"wall": {"exists": true, "position": [0,0,500]}}')

監査

scene_review()  # 11 deterministic checks, 0-100 score
scene_validate(rules='[{"type": "min_clearance", "value": 180}]')

カメラ

camera_create(target="product_display", shot_type="medium", azimuth=30, elevation=15)
# extreme_wide / wide / medium / close / extreme_close / bird_eye / low_angle / over_shoulder
camera_orbit(center=[0, 100, 0], radius=500, frames=120)

障害復旧

scene_checkpoint(name="before_renovation")  # exportAll in-memory snapshot; no undo history
scene_checkpoint_list()
scene_rollback(filename="cp_before_renovation.ma")
# auto safety snapshot first, then rebinds the scene name to the original path
# call scene_snapshot() after a rollback — snapshots carry no undo history
# self-contained: references are flattened (no write-back); one scene file per session assumed

アセット（Poly Haven、ホスト側ダウンロード）

asset_search(query="camera", asset_type="models", limit=20)  # Poly Haven index
asset_import(asset_id="Camera_01", resolution="1k")
# HTTPS-only download into a platformdirs cache (per-file md5 verify + sha256 audit),
# then Maya imports the local FBX under GRP_asset_<asset_id> (repeat calls dedup;
# force=True re-imports). Textures auto-wire by filename suffix
# (diff/rough/metal/nor_gl/ao/disp...) with sRGB/Raw color spaces and bump2d normals.
# Single-part assets ship bare map names (Diffuse/Rough/Metal...) — those are
# recognised too and wired onto the asset's single material.
# Guards: 100k-face polycount cap (allow_high_polycount override), dims sanity report.

シーンのエクスポート

scene_export(path="D:/out/scene.fbx")  # whole scene; format inferred from .fbx
scene_export(path="/tmp/kit", format="obj")  # missing extension is appended -> kit.obj
scene_export(path="D:/out/kit.usd", objects=["GEO_box"])  # exportSelected; prior selection restored
# format {fbx,obj,usd}: an extension/format conflict is an error, never a guess.
# An existing file is rejected unless overwrite=True. prompt=False is forced
# (no modal can hang the channel); the scene's modified flag is untouched.
# Alembic is not supported — AbcExport is not a cmds.file surface.

ビジュアルループ（GUI セッションのみ）

scene_viewport_snapshot(
    max_size=800, format="jpeg"
)  # HUD/selection included — what the artist sees
scene_render_preview(camera="CAM_hero", width=640, height=360)  # clean single-frame playblast
# both return [image, JSON metadata]; headless sessions get a gui_session_required error
# prefer format="png" for wireframe/line-art review; trust returned metadata for actual size

CoS 表記法

デフォルトの出力では、シーンデータを圧縮するために Chain-of-Symbol 表記法を使用します。この形式の論文では、デモシーンにおいて JSON と比べて約 65% のトークン削減が報告されています（arXiv:2305.10276、−65.8%）。このプロジェクトはその表記法を実装しています。この数値は論文での測定値であり、このプロジェクトのベンチマークではありません。

SCENE[164obj, 5zones] UNIT=cm UP=y
shell (23obj) @(-11.8,178.8,145.7)
  GRP_floor[mesh]@(0,0,0) 1121.5x20x1530.5

エージェントスキル

skills/ には、実験的なプロセスカードが2つ含まれています。

スキル	目的
skills/icev-workflow	ICEV の徹底：シーンの変更はすべて Inspect→Compute→Execute→Verify を経由します
skills/scene-review-playbook	監査プレイブック：11 項目のチェックで評価される内容と、検出結果を修正に結び付ける方法

Claude Code のみで評価済みです。Codex/Gemini CLI/Cursor では未テストです。モデルをまたいだ評価の進捗は issue #3 で追跡しています。

scene_review() は、汎用的な11項目のチェックを提供します（スコアは0～100に正規化されます）。

チェック	最大点数	確認対象
spatial	10	オブジェクト／カメラ／ライトの有無
overlaps	10	バウンディングボックスの衝突（親子間は除外）
conflicts	10	無関係なオブジェクト間の貫通
zones	5	命名規則に基づくゾーンの網羅状況
naming	5	制作時の命名規則
components	10	GRP_ によるグループ化とネストの深さ ≤ 4
orphans	5	空のグループ／デフォルト名
aesthetics	15	5つの次元での美観（色／構図／スケール／ライティング／流れ）
lighting	10	3点照明の設定、フィル比、減衰
organization	10	階層構造全体の健全性
constraints	5	カスタムルール違反

信頼性とプライバシー

• テレメトリーなし：ホームへの通信はありません。このプロジェクトにはテレメトリーや、要求されていない外向きの通信は含まれていません。ソースコードで確認できます。外部への呼び出しは、2つのアセットツールのみです。api.polyhaven.com / dl.polyhaven.org|.com への HTTPS 通信（polyhaven.py でホストの許可リスト、md5、サイズ上限を設定）であり、ツールを呼び出した場合にのみ行われます。
• ローカル、シングルユーザー：コマンドポートは localhost のみにバインドされます。接続された MCP クライアントは信頼済みとして扱われます。
• 安全対策：統合パイプライン（pipeline.py + security.py）により、引数の検証、トークンバケット方式のレート制限（セッションごとに読み取り約100回／60秒、書き込み約20回／60秒）、パターンスキャン（デフォルトでは警告のみ）、全25ツールを対象とする独立した JSONL 監査ログを実施します。これは誤操作を検出するものであり、悪意のあるクライアントを防ぐものではありません。全体像は docs/threat-model.md をご覧ください。
• トランザクションの安全性：scene_checkpoint／scene_rollback により、メモリ内のスナップショットを作成し、明示的にロールバックできます（Undo 履歴はなく、参照はフラット化されます）。
• 厳格なポリシーモード（任意）：MAYA_MCP_DISABLE_EXECUTE=1、MAYA_MCP_DISABLE_WRITE_MODULE=1、または MAYA_MCP_DISABLE_ARBITRARY=1（3つすべて）を設定すると、エスケープハッチツールが tools/list から削除され、呼び出しは [policy_disabled] で拒否されます。読み取り専用ツールには影響しません。これらは誤用を防ぐためのガードレールであり、敵対的なエージェントを隔離する境界ではありません。execute_code を引き続き使用できるエージェントは、すでに信頼境界の内側にいます。これにより得られるのは、デモ、ミス、CI サンドボックスにおける被害範囲の縮小です。背景については docs/threat-model.md をご覧ください。コードごとのリファレンスは docs/guide/error-codes.md をご覧ください。
• 脆弱性の報告先：SECURITY.md。

バージョニング

このプロジェクトはセマンティックバージョニングに従います。

• 0.x（0.3.x まで、アルファ）：ツールの公開範囲は引き続き変更される可能性があり、マイナーバージョンの更新では機能が追加されますが、互換性は保証されません。
• ベータ（0.4.0）：機能が出そろった段階です。ここから外部テストを開始します（classifier 4 - Beta）。
• 1.0.0：パブリック API を凍結します。セマンティックバージョニングに従い、ツールの公開範囲と出力スキーマを安定させます。破壊的変更には 2.0.0 が必要です。5 - Production/Stable classifier と同じコミットで昇格します。#7 の実機チェックリストによるゲート条件があります（合格項目がすべて完了し、免除項目には担当者と期限が明示されていること。3 状態のゲート、D-163）。

パブリック APIとは、MCP ツールの公開範囲を指します。具体的には、ツール名、入力／出力の形式、2 層のエラー契約（ホストの isError による失敗と、{error:{code,message,suggestion}} 形式のドメイン結果）、およびツールアノテーションの意味です（docs/threat-model.md §5）。追加的な変更（新しいツール、新しい任意のレスポンスフィールド）はマイナーリリースとして提供し、破壊的変更はメジャーバージョンを上げて提供します。1.0.0 はこの公開範囲を凍結するという約束であり、品質認証ではありません。残る実機での検証範囲は、暗黙に除外せず、#7 で明示的に追跡します。

リリースはマイルストーンに基づいており、固定のリリース間隔は約束しません。ロードマップは GitHub の Issue で管理しています。#2 Poly Haven 連携（モデル部分は 0.2.0 で提供済み。scene_plan の推奨に関する残件は #31 に分割）、#3 Skills プログラム（v1.x）、#4 セキュリティと権限モデル（v1.x）、#5 シーンのエクスポートとイントロスペクション（scene_export は FBX／OBJ／USD に対応して 0.3.0 で提供済み。scene_describe／scene_nodes によるイントロスペクションも同じ 0.3.0 で提供済み）、#6 その他のアセットソース（調査中）、#7 実機チェックリストと v1.0 へのフィードバック（ピン留め）。

要件

環境	要件
ホスト（MCP サーバーを実行）	Python >= 3.10（requires-python）。Windows／Linux／macOS
注入されるヘルパー（Maya 内で実行）	Maya >= 2023（同梱の Python >= 3.9。ast.unparse に依存しており、それより古いバージョンでは注入時に明示的に拒否されます）
検証済み環境	Maya 2024 GUI

2 つのビジュアルループツールには GUI セッションが必要です（ヘッドレス環境／mayapy では構造化された機能エラーが返されます）。最初のキャプチャ時に、サーバーはセッションごとに VP2 の読み戻し方向を調査します（破棄可能なシーンを使ったプローブで、副作用は差し引きゼロです）。ドライバーが誤った方向を報告する場合は、MAYA_MCP_VP2_BOTTOM_UP=0|1 で指定できます。

開発

uv sync --frozen                  # locked dev env from uv.lock (alt: pip install -e . --group dev, pip>=25.1)
python -m pytest tests/ -q       # tests
ruff check src tests             # lint
mypy src                         # typecheck
python -m maya_mcp_server -vv    # run with DEBUG logs (-v=INFO, -vv=DEBUG)

PR の手順についてはCONTRIBUTING.mdを、変更履歴についてはCHANGELOG.mdを参照してください。

クレジット

chadrik/maya-mcp-serverからフォークしました。上流の MIT 著作権表示はそのまま保持しています（LICENSE を参照）。このプロジェクトでは、その接続スタックの上にシーンインテリジェンス層を追加しています。

上流の各オープン Issue がこのフォークでどのように扱われ、どのリリースバージョンに対応するかについては、docs/upstream-issue-status.mdを参照してください。