Cinema4D MCP — Model Context Protocol (MCP) Server

Cinema4D MCP — Model Context Protocol（MCP）サーバー

Cinema4D MCP サーバーは Cinema 4D を Claude に接続し、プロンプトを使った 3D 操作を可能にします。

目次

• コンポーネント
• 前提条件
• インストール
• セットアップ
• 使い方
• エージェントスキル
• 開発
• トラブルシューティングとデバッグ
• ファイル構成
• ツールコマンド
• 使い方ガイド — 実用的なヒント、抽出パターン、既知の問題

コンポーネント

1. C4D プラグイン：MCP サーバーからのコマンドを受け付け、Cinema 4D 環境で実行するソケットサーバーです。
2. MCP サーバー：MCP プロトコルを実装し、Cinema 4D との連携に使うツールを提供する Python サーバーです。

前提条件

• Cinema 4D（R2024 以降を推奨）
• Python 3.10 以降（MCP サーバーコンポーネント用）

インストール

プロジェクトをインストールするには、次の手順に従ってください。

リポジトリをクローンする

git clone https://github.com/ttiimmaacc/cinema4d-mcp.git
cd cinema4d-mcp

MCP サーバーパッケージをインストールする

pip install -e .

ラッパースクリプトを実行可能にする

chmod +x bin/cinema4d-mcp-wrapper

セットアップ

Cinema 4D プラグインのセットアップ

Cinema 4D プラグインをセットアップするには、次の手順に従ってください。

1. プラグインファイルをコピーする：c4d_plugin/mcp_server_plugin.pyp ファイルを Cinema 4D のプラグインフォルダーにコピーします。パスはオペレーティングシステムによって異なります。

   • macOS：/Users/USERNAME/Library/Preferences/Maxon/Maxon Cinema 4D/plugins/
   • Windows：C:\Users\USERNAME\AppData\Roaming\Maxon\Maxon Cinema 4D\plugins\

2. ソケットサーバーを起動する：

   • Cinema 4D を開きます。
   • ［Extensions］>［Socket Server Plugin］に移動します。
   • ［Socket Server Control］ダイアログが表示されます。［Start Server］をクリックします。

Claude Desktop の設定

Claude Desktop を設定するには、設定ファイルを変更する必要があります。

1. 設定ファイルを開く：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • または、Claude Desktop の［Settings］メニュー（［Settings］>［Developer］>［Edit Config］）を使用します。

2. MCP サーバーの設定を追加する： 開発中または未公開のサーバーの場合、次の設定を追加します。

   "mcpServers": {
     "cinema4d": {
       "command": "python3",
       "args": ["/Users/username/cinema4d-mcp/main.py"]
     }
   }
   

3. 設定ファイルを更新した後、Claude Desktop を再起動します。

{
  "mcpServers": {
    "cinema4d": {
      "command": "cinema4d-mcp-wrapper",
      "args": []
    }
  }
}

使い方

1. Cinema 4D のソケットサーバーが実行中であることを確認します。
2. Claude Desktop を開き、入力ボックスにハンマーアイコン 🔨 が表示されていることを確認します。これは MCP ツールが利用可能であることを示します。
3. 利用可能なツールコマンドを使って、Claude 経由で Cinema 4D を操作します。

エージェントスキル

エージェントスキルを使用する場合、この MCP に対応するメンテナンス対象のスキルは vladmdgolam/agent-skills にあります。

このスキルでは、生の MCP ツールを補完する、実制作を想定したガイダンスを提供します。内容は次のとおりです。

• Redshift の調査では、その場で Python を使うより inspect_redshift_materials を優先するタイミング
• C4D API に完全にアクセスするため execute_python_script に切り替えるタイミング
• ランタイムまたはノードスペースが利用できない場合の、現在の Redshift の制限
• MoGraph の実用的な抽出およびデバッグのワークフロー

テスト

コマンドラインでのテスト

コマンドラインから Cinema 4D ソケットサーバーを直接テストするには、次のようにします。

python main.py

サーバーが正常に起動し、Cinema 4D に接続されたことを示す出力が表示されます。

MCP Test Harness を使用したテスト

このリポジトリには、あらかじめ定義されたコマンドシーケンスを実行するためのシンプルなテストハーネスが含まれています。

1. テストコマンドファイル（tests/mcp_test_harness.jsonl）：順番に実行できるコマンドシーケンスが JSONL 形式で含まれています。各行は、パラメーターを指定した単一の MCP コマンドを表します。

2. GUI テストランナー（tests/mcp_test_harness_gui.py）：テストコマンドを実行するためのシンプルな Tkinter GUI です。

   python tests/mcp_test_harness_gui.py
   

   GUI では次の操作ができます。

   • JSONL テストファイルを選択する
   • コマンドを順番に実行する
   • Cinema 4D からの応答を確認する

このテストハーネスは、特に次の用途に便利です。

• 新しいコマンドをすばやくテストする
• アップデート後にプラグインの機能を検証する
• デバッグ用に複雑なシーンを再作成する
• 異なる Cinema 4D バージョン間の互換性をテストする

トラブルシューティングとデバッグ

1. ログファイルを確認します。

   tail -f ~/Library/Logs/Claude/mcp*.log
   

2. Claude Desktop を開いた後、Cinema 4D のコンソールに接続が表示されていることを確認します。

3. ラッパースクリプトを直接テストします。

   cinema4d-mcp-wrapper
   

4. mcp モジュールが見つからないというエラーが発生する場合は、システム全体にインストールします。

   pip install mcp
   

5. 高度なデバッグには、MCP Inspector を使用します。

   npx @modelcontextprotocol/inspector uv --directory /Users/username/cinema4d-mcp run cinema4d-mcp
   

プロジェクトのファイル構成

cinema4d-mcp/
├── .gitignore
├── LICENSE
├── README.md
├── main.py
├── pyproject.toml
├── setup.py
├── bin/
│   └── cinema4d-mcp-wrapper
├── c4d_plugin/
│   └── mcp_server_plugin.pyp
├── src/
│   └── cinema4d_mcp/
│       ├── __init__.py
│       ├── server.py
│       ├── config.py
│       └── utils.py
└── tests/
    ├── test_server.py
    ├── mcp_test_harness.jsonl
    └── mcp_test_harness_gui.py

ツールコマンド

シーンと実行全般

• get_scene_info：アクティブな Cinema 4D シーンの概要情報を取得します。✅
• list_objects：シーン内のすべてのオブジェクトを一覧表示します（階層を含む）。✅
• group_objects：選択したオブジェクトを新しいヌルオブジェクトの下にグループ化します。✅
• execute_python：Cinema 4D 内でカスタム Python コードを実行します。✅
• save_scene：現在の Cinema 4D プロジェクトをディスクに保存します。✅
• load_scene：.c4d ファイルをシーンに読み込みます。✅
• set_keyframe：オブジェクトのプロパティ（位置、回転など）にキーフレームを設定します。✅

オブジェクトの作成と変更

• add_primitive：プリミティブ（立方体、球体、円錐など）をシーンに追加します。✅
• modify_object：既存のオブジェクトのトランスフォームまたは属性を変更します。✅
• create_abstract_shape：有機的で標準的ではない抽象形状を作成します。✅

カメラとアニメーション

• create_camera：新しいカメラをシーンに追加します。✅
• animate_camera：パス（直線またはスプラインベース）に沿ってカメラをアニメーション化します。✅

ライティングとマテリアル

• create_light：ライト（全方向、スポットなど）をシーンに追加します。✅
• create_material：標準的な Cinema 4D マテリアルを作成します。✅
• apply_material：対象オブジェクトにマテリアルを適用します。✅
• apply_shader：スタイライズドシェーダーまたはプロシージャルシェーダーを生成して適用します。✅

Redshift のサポート

• inspect_redshift_materials：割り当て、プレビューカラー、読み取り可能なパラメーターのフォールバック、renderEngine 形式のノードマテリアルプローブ、redshift.GetRSMaterialNodeMaster(...) を介した Redshift GraphView のフォールバックに対応した、読み取り専用の Redshift インスペクターです。✅ 既知の癖：マテリアルごとの GraphView フォールバックが成功していても、一部のビルドでは最上位の capabilities.redshift_module_available フラグが false のままになることがあります。各マテリアルの graph.backend と graph.graphview.redshift_module_imported を、信頼できる判断材料として扱ってください。
• validate_redshift_materials：Redshift マテリアルの設定と接続を確認します。✅ ⚠️（Redshift マテリアルは完全には実装されていません）

MoGraph とフィールド

• create_mograph_cloner：MoGraph Cloner（リニア、ラジアル、グリッドなど）を追加します。✅
• add_effector：MoGraph Effector（Random、Plain など）を追加します。✅
• apply_mograph_fields：MoGraph Field を追加し、オブジェクトにリンクします。✅

ダイナミクスと物理演算

• create_soft_body：オブジェクトに Soft Body タグを追加します。✅
• apply_dynamics：剛体またはソフトボディの物理演算を適用します。✅

レンダリングとプレビュー

• render_frame：フレームをレンダリングしてディスクに保存します（ファイル出力のみ）。⚠️（動作しますが、解像度が大きいと MemoryError: Bitmap Init failed が発生して失敗します。これはリソース上の制限です。）
• render_preview：クイックプレビューをレンダリングし、（AI 用の）Base64 画像を返します。✅
• snapshot_scene：シーンのスナップショット（オブジェクトとプレビュー画像）をキャプチャします。✅

互換性計画とロードマップ

互換性の目標

• 短期：C4D 2023.1 以降（Python 3.9 および 3.10）との互換性を確保します
• 中期：MoGraph および Field API が存在しない場合の条件付き処理を追加します
• 長期：需要が生じた場合、R23～S26 をサポートするオプションのレガシープラグインモジュールを検討します

最近の修正

• コンテキスト認識：GUID を使用した堅牢なオブジェクト追跡を実装しました。オブジェクトを作成するコマンドは、コンテキスト（guid、actual_name など）を返します。後続のコマンドは、テストハーネス／サーバーから渡された GUID を正しく使用して、オブジェクトを確実に検索します。
• オブジェクト検索：find_object_by_name を改修し、GUID（数値文字列形式）を正しく処理するようにしました。再帰エラーを修正し、doc.SearchObject が失敗した場合の信頼性を向上させました。
• GUID の検出：コマンドハンドラー（apply_material、create_mograph_cloner、add_effector、apply_mograph_fields、set_keyframe、group_objects）が、さまざまなパラメーター（object_name、target、target_name、リスト項目）で渡された識別子が GUID かどうかを正しく検出し、それに応じて検索するようになりました。
• create_mograph_cloner：getattr による代替処理を使用して、MoGraph パラメーター（MG_LINEAR_PERSTEP など）が存在しない場合の AttributeError を修正しました。見つかったオブジェクトがクローン作成に正しく渡されないロジックの不具合も修正しました。
• レンダリング：doc.ExecutePasses に関連する render_frame の TypeError を修正しました。snapshot_scene で、正常に動作する base64 レンダリングロジックが正しく使用されるようになりました。大きな render_frame では、引き続きメモリ制限が発生します。
• 登録：c4d.NilGuid に関連する AttributeError を修正しました。