Model Context Protocol を介した Blender 5.x 向けのAI駆動2D描画・アニメーション。MCPクライアント（Claude Desktop、Cursor、VS Code Copilot agent mode など）が、実行中のBlenderインスタンス内で直接Grease Pencilの描画、キーフレーム、マテリアル、レンダーを作成できます。
Blenderの GPv3 API（bpy.ops.grease_pencil.*、GreasePencilDrawing）上に構築されており、ahujasid/blender-mcp を参考にしています。
flowchart LR
A[MCP Client<br/>Claude / Cursor / VS Code] <-->|stdio / JSON-RPC| B[blender-2d-mcp<br/>FastMCP server]
B <-->|TCP JSON<br/>localhost:9876| C[addon.py<br/>socket server in Blender]
C -->|main thread| D[Grease Pencil API<br/>GPv3]addon.py — TCP JSONコマンドサーバーを内蔵したBlenderアドオン。コマンドはキューに積まれ、bpy.app.timers を介してBlenderのメインスレッドで実行されます。
src/blender_2d_mcp/server.py — アドオンのコマンドをMCPツールとして公開するFastMCP stdioサーバー。
Blender 5.2 LTSのみ（アドオンは旧バージョンでは有効化を拒否します。使用するGPv3 APIサーフェスは5.2固有です）
Python ≥ 3.10 と mcp[cli]（自動インストールされます）
Related MCP server: Blender MCP Bridge
Blenderで: Edit > Preferences > Add-ons > Install…
このリポジトリから addon.py を選択。
Interface: Blender 2D MCP を有効化。
サイドバーを開く（View > Sidebar、または N キー）→ Blender2DMCP タブ。
Connect to MCP Client をクリック（デフォルトポート 9876）。Blenderは起動したままにしてください。
ヒント:
blender-2d-mcp --install-addonを実行するとaddon.pyがダウンロードフォルダにコピーされ、これらの手順が表示されます。
サーバーは localhost のみにバインドします。ローカル利用には認証トークンは不要です。
オプションA — uvx（インストール不要）:
uvx --from "g:\My Projects\blender-2d-mcp" blender-2d-mcpオプションB — 編集可能インストール:
cd "g:\My Projects\blender-2d-mcp"
pip install -e .
blender-2d-mcp # runs the stdio MCP serverClaude Desktop（claude_desktop_config.json）:
{
"mcpServers": {
"blender-2d-mcp": {
"command": "uvx",
"args": ["--from", "g:\\My Projects\\blender-2d-mcp", "blender-2d-mcp"]
}
}
}Cursor（.cursor/mcp.json）または汎用stdioクライアント:
{
"mcpServers": {
"blender-2d-mcp": {
"command": "C:\\Path\\To\\Python\\Scripts\\blender-2d-mcp.exe",
"args": []
}
}
}VS Code / GitHub Copilot Chat（.vscode/mcp.json — このリポジトリに同梱済み）:
{
"servers": {
"blender-2d-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "g:\\My Projects\\blender-2d-mcp", "blender-2d-mcp"],
"env": {}
}
}
}別の方法として、
blender_2d_mcpが何らかの環境にpipインストールされている場合は、その環境のPythonを使用します:"command": "C:\\Path\\To\\Python\\python.exe", "args": ["-m", "blender_2d_mcp.server"]。
使用方法: Copilot Chatを開き、モードドロップダウンを Agent に切り替えると、Blenderツールが利用可能になります（#blender-2d-mcp）。コマンドパレットから MCP: List Servers でサーバーの開始・停止・再起動ができます。mcp.json を編集した後はVS Codeウィンドウをリロードしてください。
setup_2d_scene を使用すると、ビューポートが正面の正投影ビューに設定されるため、描画平面はワールド XZ になります:
送信する2Dポイント | ワールド位置 | 意味 |
|
| x = 画面右方向、y = 画面上方向 |
|
| そのまま使用 |
単位はメートル（Blenderのデフォルト）です。デフォルトのカメラズームでの1920×1080 HDフレームは、水平方向に約±5単位の範囲になります。
ツール | 目的 |
| GPオブジェクト、レイヤー、キーフレーム、ストローク数の一覧表示 |
| 一般的なシーン/オブジェクトのイントロスペクション |
| アドオン/プロトコル/Blenderバージョン + 互換性ステータス |
| 白背景、正面正投影ビュー、HD解像度 |
| レイヤー + 黒ストロークマテリアルを持つ新しいGPオブジェクト |
| レイヤー管理 |
| レイヤースタックの編集 |
| 不透明度、ブレンドモード、非表示、ロック |
| GPv3レイヤーマスキング（切り抜き効果） |
| 冪等な空白キーフレーム作成 |
| キーフレーム操作（ |
| フリーフォームストローク。テーパリング用のポイントごとの半径/不透明度プロファイル |
| 1回の呼び出しで多数のストロークを一括描画 |
|
|
| ストロークの検査と編集（移動/拡大縮小/回転/スムーズ） |
| ストローク + 塗りつぶしの色 |
| 2つのキーフレーム間の中間フレームを生成（イージング制御） |
| キーフレームのオブジェクト位置/回転/スケール |
| 前後のフレームをゴースト表示 |
| GPモディファイア: Noise wobble、Smooth、Thickness、Time offset… |
| 再生ヘッド、fps、フレーム範囲、レンダーエンジン、フィルム透過 |
| キャンバスにフィットした正面正投影カメラ |
| トレース用の背景画像エンプティ |
| mp4動画出力を含むノンブロッキングレンダー |
| AI駆動の編集を元に戻す |
| ビューポートのキャプチャを画像として返す |
| 脱出ハッチ: 任意の |
| 最終手段としての任意の |
get_gp_scene_info + get_viewport_screenshot — 既存の状態を確認。
新規開始の場合は setup_2d_scene → create_gp_object。
gp_draw_shape / gp_draw_stroke で描画。frame_number を渡すとキーポーズにストロークを配置できます（フレームは自動的に作成されます）。詳細な描画の一括作成には gp_draw_strokes を使用。
塗りつぶしシェイプ: fill_alpha > 0 のマテリアルを作成し、fill=True + fill_material を指定。
「2コマ打ち」でアニメーション（24fpsで2フレームごとにキーポーズ）: gp_copy_frame でポーズをコピーし、gp_transform_stroke で調整、gp_interpolate で中間フレームを生成。手描き風の揺れにはNOISEモディファイアを追加。
render_animation(use_video=True) でレンダリングし、get_render_status でポーリング。
変更後は必ずスクリーンショットを撮って視覚的に確認。ミスは undo で取り消せます。
pip install -e ".[dev]"
python -m pytest tests/ -vテストスイートは、Blenderの外部でアドオンのTCPトランスポートを実行します。サーバークラスを偽の bpy に対してASTリフティングすることで、Blenderのインストールは不要です。実際のGrease Pencilデータに触れるハンドラーロジックは、Blender内で検証する必要があります。
症状 | 修正方法 |
MCPクライアントが接続できない | 最初にBlenderのサイドバーパネルでサーバーを起動してください。ポートが一致しているか確認してください（デフォルトは9876） |
ポートが既に使用されている | サイドバーパネルでポートを変更し、MCPコマンドに |
起動時のファイアウォールプロンプト | プライベートネットワークでBlenderを許可してください（サーバーはlocalhostのみにバインドされます） |
スクリーンショットが黒い | Blenderウィンドウ内を一度クリックしてください（コンポジターの問題）、または3Dビューポートが表示されていることを確認してください。ツールはオフスクリーンGPUキャプチャからウィンドウグラブに自動的にフォールバックします |
| Blenderで表示可能な3Dビューポートと、両方の境界フレームにキーフレームが必要です。ビューポートを開いてください |
モーダルオペレーター（ペン、ブラシストローク）が機能しない | MCPではサポートされていません — 代わりに |
| 使用されなくなりました — MCPサーバーを再起動し、アドオンと |
レンダリングがハングするように見える | 現在はノンブロッキングです — |
アドオンが有効化できない | このプロジェクトはBlender 5.2 LTSを正確に必要とします（GPv3 APIのみ）。古いビルドは設計上拒否されます |
MIT
This server cannot be deployed
Generate AI images and videos from any compatible MCP client.
Generate images, video, audio and short films with 140+ AI models from any MCP client.
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
