# Code created by Siddharth Ahuja: www.github.com/ahujasid © 2025 import math import re import textwrap import bpy import mathutils import json import threading import socket import select import ipaddress import queue import time import requests import tempfile import traceback import os import shutil import uuid import zipfile import zlib from bpy.props import IntProperty, BoolProperty import io from datetime import datetime import hashlib, hmac, base64 import os.path as osp from collections import deque from urllib.parse import quote, urlencode, urljoin, urlparse, urlunparse, parse_qsl from contextlib import contextmanager, redirect_stdout, suppress from bpy.app.handlers import persistent bl_info = { "name": "MCP for Blender", "author": "Siddharth Ahuja", "version": (2, 0), "blender": (3, 0, 0), "location": "View3D > Sidebar > MCP for Blender", "description": "Connect Blender to Claude via MCP", "doc_url": "https://mcp-for-blender.com/", "category": "Interface", } # Keep in sync with blender_mcp.addon_manager.EXPECTED_ADDON_PROTOCOL_VERSION. ADDON_PROTOCOL_VERSION = 16 # Per-snapshot object cap for get_world_state_snapshot. Keep in sync with # blender_mcp.trajectory.MAX_SNAPSHOT_OBJECTS. MAX_SNAPSHOT_OBJECTS = 4000 # Selected-name cap for get_world_state_snapshot: select-all in a large scene # would otherwise make `selected` the dominant field of both step snapshots. # Keep in sync with blender_mcp.trajectory.MAX_SNAPSHOT_SELECTED. MAX_SNAPSHOT_SELECTED = 1000 RODIN_FREE_TRIAL_KEY = "vibecoding" DISCORD_URL = "https://discord.gg/SNqPn4TcKQ" # Add User-Agent as required by Poly Haven API REQ_HEADERS = requests.utils.default_headers() REQ_HEADERS.update({"User-Agent": "blender-mcp"}) # Meshy, with the user's own key. Sidebar model id -> label; the id is what # the request sends. Text runs as a preview task, then one refine task. MESHY_API_BASE = "https://api.meshy.ai/openapi" MESHY_DEFAULT_MODEL = "latest" MESHY_MODELS = { "latest": "Meshy 7.1", "meshy-6": "Meshy 6", } MESHY_KEY_URL = ("https://www.meshy.ai/developers/keys" "?utm_source=mcp-for-blender&utm_medium=integration&utm_campaign=blender-addon") MESHY_PROMPT_MAX = 800 MESHY_POSES = ("a-pose", "t-pose") MESHY_IMAGE_MAX_BYTES = 20 * 1024 * 1024 MESHY_IMAGE_TYPES = {".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp"} # Every task: GLB only, sized to real-world height, origin at the bottom. MESHY_OUTPUT = {"target_formats": ["glb"], "auto_size": True, "origin_at": "bottom"} MESHY_HEADERS = {"User-Agent": "mcp-for-blender/" + ".".join(str(part) for part in bl_info["version"])} MESHY_TIMEOUT = (10, 60) # Preview task id -> refine task id. Blender runs commands one at a time, so # this is where a repeated refine request (after the MCP side lost the reply to # a socket timeout, or from a second MCP server) gets the refine already paid for. _meshy_refines = {} # Tripo, with the user's own key. Sidebar model id -> label; the id is what # the request sends. Text and image are each one task. TRIPO_DOMAINS = [ ("ai", ".ai", "Use the international Tripo API and developer portal"), ("com", ".com", "Use the CN Tripo API and developer portal"), ] TRIPO_DEFAULT_MODEL = "v3.1-20260211" TRIPO_MODELS = { "v3.1-20260211": "H3.1", "P2-20260801": "P2.0", } TRIPO_PROMPT_MAX = 1024 TRIPO_IMAGE_MAX_BYTES = 20 * 1024 * 1024 TRIPO_IMAGE_TYPES = {".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png"} TRIPO_HEADERS = {"User-Agent": "mcp-for-blender/" + ".".join(str(part) for part in bl_info["version"])} TRIPO_TIMEOUT = (10, 60) # World Labs Marble: whole worlds as Gaussian splats, which Blender imports # from 5.3 on. Sidebar model id -> label; the id is what the request sends. WORLDLABS_API_BASE = "https://api.worldlabs.ai/marble/v1" WORLDLABS_DEFAULT_MODEL = "marble-1.1-plus" WORLDLABS_MODELS = { "marble-1.1-plus": "Marble 1.1 Plus", "marble-1.1": "Marble 1.1", } # Premium's model; the Premium server decides, this only names it in replies. WORLDLABS_PREMIUM_MODEL = "marble-1.1" WORLDLABS_KEY_URL = "https://platform.worldlabs.ai/api-keys" WORLDLABS_MIN_BLENDER = (5, 3, 0) WORLDLABS_IMAGE_MAX_BYTES = 10 * 1024 * 1024 # World Labs' limit for inline images WORLDLABS_MAX_IMAGES = 4 WORLDLABS_IMAGE_SUFFIXES = (".png", ".jpg", ".jpeg", ".webp") WORLDLABS_RESOLUTIONS = ("100k", "500k", "full_res") WORLDLABS_HEADERS = {"User-Agent": "mcp-for-blender/" + ".".join(str(part) for part in bl_info["version"])} WORLDLABS_TIMEOUT = (10, 60) # Set when the user disconnects so opening another blend file does not restart # the server behind their back. A manual connect or add-on reload clears it. _user_stopped_server = False def _blendermcp_bind_address(context=None): """Read persistent listener settings, requiring opt-in beyond loopback.""" prefs = get_blendermcp_addon_preferences(context) host = getattr(prefs, "bind_address", "localhost").strip() if host.lower() == "localhost": return "localhost" try: address = ipaddress.IPv4Address(host) except ipaddress.AddressValueError as exc: raise ValueError("Bind Address must be localhost or an IPv4 address") from exc if not address.is_loopback and not getattr(prefs, "allow_remote_connections", False): raise ValueError( "Non-loopback binding requires Allow Remote Connections in add-on preferences" ) return str(address) def _blendermcp_port_has_listener(host, port): """Return True when another process already owns the MCP endpoint.""" probe = socket.socket(socket.AF_INET, socket.SOCK_STREAM) probe.settimeout(0.15) try: # A wildcard is a listening address, not a portable connect target. probe_host = "127.0.0.1" if host == "0.0.0.0" else host return probe.connect_ex((probe_host, port)) == 0 finally: probe.close() def _blendermcp_ensure_server_running(): """Start the bridge after Blender's UI and scene context are ready. Returning a delay asks Blender's timer system to retry when a launch-time socket or context race prevented the first attempt. """ if bpy.app.background: return None scene = getattr(bpy.context, "scene", None) if scene is None: return 0.5 server = getattr(bpy.types, "blendermcp_server", None) if not scene.blendermcp_auto_start_server or _user_stopped_server: scene.blendermcp_server_running = bool(server is not None and server.running) return None if server is not None and server.running: scene.blendermcp_server_running = True return None try: host = _blendermcp_bind_address() except ValueError as exc: scene.blendermcp_server_running = False print(f"BlenderMCP: auto-start skipped: {exc}") return None port = scene.blendermcp_port if server is None: if _blendermcp_port_has_listener(host, port): scene.blendermcp_server_running = False print(f"BlenderMCP: {host}:{port} is already in use; auto-start skipped.") return None server = BlenderMCPServer(host=host, port=port) bpy.types.blendermcp_server = server if not server.running: # Safe while stopped and necessary when a newly loaded scene selects a # different port or the preferences select a different bind address. # Never retarget an active connection. server.host = host server.port = port server.start() scene.blendermcp_server_running = server.running return None if server.running else 1.0 def _blendermcp_schedule_auto_start(delay=0.5): """Schedule one persistent startup callback if none is already pending.""" if not bpy.app.timers.is_registered(_blendermcp_ensure_server_running): bpy.app.timers.register( _blendermcp_ensure_server_running, first_interval=delay, persistent=True, ) @persistent def _blendermcp_load_post(_unused): """Retry auto-start after Blender loads a startup file or another blend.""" _blendermcp_schedule_auto_start() def _blendermcp_register_auto_start(): """Install the load handler and defer the initial startup attempt.""" global _user_stopped_server _user_stopped_server = False if _blendermcp_load_post not in bpy.app.handlers.load_post: bpy.app.handlers.load_post.append(_blendermcp_load_post) _blendermcp_schedule_auto_start() def _blendermcp_unregister_auto_start(): """Remove callbacks owned by the add-on before it is disabled.""" if _blendermcp_load_post in bpy.app.handlers.load_post: bpy.app.handlers.load_post.remove(_blendermcp_load_post) if bpy.app.timers.is_registered(_blendermcp_ensure_server_running): bpy.app.timers.unregister(_blendermcp_ensure_server_running) #region Poly Pizza constants and helpers POLYPIZZA_API_BASE = "https://api.poly.pizza/v1.1" # The MCP server resolves human-friendly category/licence names to the numeric # ids the API filters on, so only ids arrive here. Every query parameter of # the API is Capitalized (Limit, Page, Category, License, Animated — see # poly.pizza/apispec/v1.1.yaml): lowercase variants are accepted with HTTP 200 # and then silently ignored, so the capitalisation is load-bearing. def _polypizza_category_id(category): """Validate a numeric category id (names are resolved by the MCP server).""" if category is None or category == "": return None if isinstance(category, bool) or not ( isinstance(category, int) or (isinstance(category, str) and category.strip().lstrip("-").isdigit()) ): raise ValueError(f"Poly Pizza category must be a numeric id in 0-11, got {category!r}") value = int(category) if not 0 <= value <= 11: raise ValueError(f"Poly Pizza category id {value} is out of range (valid ids are 0-11)") return value def _polypizza_licence_id(licence): """Validate a numeric licence id (names are resolved by the MCP server).""" if licence is None or licence == "": return None if isinstance(licence, bool) or not ( isinstance(licence, int) or (isinstance(licence, str) and licence.strip().lstrip("-").isdigit()) ): raise ValueError(f"Poly Pizza licence must be 0 (CC-BY) or 1 (CC0), got {licence!r}") value = int(licence) if value not in (0, 1): raise ValueError(f"Poly Pizza licence id {value} is invalid (0 = CC-BY, 1 = CC0)") return value def _polypizza_filter_params(category=None, licence=None, animated=False): """Build the query filters for a Poly Pizza search. Keys are Capitalized and values numeric because the API silently ignores anything else. `Animated` is omitted unless animated-only results were asked for: the server treats `Animated=0` as falsy and does not filter on it. """ params = {} category_id = _polypizza_category_id(category) if category_id is not None: params["Category"] = category_id licence_id = _polypizza_licence_id(licence) if licence_id is not None: params["License"] = licence_id if animated: params["Animated"] = 1 return params def _polypizza_summarize_model(model): """Trim an API record down to the fields worth sending back over MCP.""" creator = model.get("Creator") or {} return { "ID": model.get("ID"), "Title": model.get("Title"), "Creator": creator.get("Username") if isinstance(creator, dict) else None, "Licence": model.get("Licence"), "Tri Count": model.get("Tri Count"), "Animated": bool(model.get("Animated")), "Category": model.get("Category"), "Tags": model.get("Tags") or [], "Thumbnail": model.get("Thumbnail"), } def _polypizza_cdn_error(status_code, headers, content): """Describe a CDN response that is not a GLB, or None when it is one. static.poly.pizza sits behind Cloudflare bot management and answers 403 with an HTML challenge from datacenter IPs. That is neither an auth failure nor a missing model, so it gets its own message. """ if status_code == 200 and content[:4] == b"glTF": return None headers = headers or {} content_type = "" for key in ("Content-Type", "content-type"): value = headers.get(key) if value: content_type = str(value).lower() break challenged = bool(headers.get("cf-mitigated") or headers.get("Cf-Mitigated")) looks_like_html = "text/html" in content_type or content[:1] == b"<" if challenged or (looks_like_html and status_code != 200): return ( f"Poly Pizza's CDN returned a Cloudflare bot-protection challenge (HTTP {status_code}) " "instead of the model file. This is not an API key problem - static.poly.pizza takes no " "API key - and the model exists. The CDN blocks datacenter, VPN and cloud IPs; retry from " "a residential connection, or download the .glb by hand from https://poly.pizza and import " "it with File > Import > glTF 2.0." ) if status_code != 200: return f"Poly Pizza model file download failed with status code {status_code}" if looks_like_html: return ( "Poly Pizza's CDN returned an HTML page instead of a GLB file. The download link may have " "expired; search again to get a fresh one." ) return "Poly Pizza returned a file that is not a valid GLB (missing glTF magic bytes)" #endregion #region Poly Haven constants and helpers POLYHAVEN_API_BASE = "https://api.polyhaven.com" # Versioned, so Poly Haven can tell which integration its traffic is coming from # and how many people it is serving. Kept separate from the shared REQ_HEADERS # because Poly Pizza sends that one too. POLYHAVEN_HEADERS = dict(REQ_HEADERS) POLYHAVEN_HEADERS["User-Agent"] = ( "blender-mcp/" + ".".join(str(part) for part in bl_info["version"]) + " (+https://github.com/ahujasid/blender-mcp)" ) # (connect, read). The read timeout applies per socket read rather than to the # whole transfer, so streaming a large HDRI never trips it - but a dead # connection no longer hangs Blender's main thread indefinitely. POLYHAVEN_API_TIMEOUT = (10, 30) POLYHAVEN_FILE_TIMEOUT = (10, 60) POLYHAVEN_CHUNK_SIZE = 1024 * 1024 # What we can actually import, per asset type. Checked BEFORE downloading # anything: the API lists a `usd` entry for every model, which used to pass the # "is this format present?" guard, get downloaded in full, and only then be # rejected as an unsupported format. POLYHAVEN_SUPPORTED_FORMATS = { "hdris": ("hdr", "exr"), "textures": ("jpg", "png", "exr"), "models": ("blend",), } POLYHAVEN_DEFAULT_FORMATS = {"hdris": "hdr", "textures": "jpg", "models": "blend"} # Models are imported from the .blend and nothing else. Poly Haven authors its # models in Blender and generates every other format from that file, so glTF and # FBX are lossy renderings of a material that is sitting right there - node # groups collapse to a base colour, and procedural setups do not survive at all. # # glTF stays as a fallback for one case only: a .blend written by a newer # Blender than the one running, which cannot be opened at all. See # _polyhaven_blend_version. POLYHAVEN_MODEL_FALLBACK_FORMAT = "gltf" # Poly Haven's /files map keys, and what each map drives. Their casing is # inconsistent and load-bearing - "Diffuse", "Rough", "Metal" and # "Displacement" are capitalised while "nor_gl" and "arm" are not - so these # are matched exactly instead of being lower-cased and guessed at. # # This is the set that drives a Principled BSDF directly, and it covers what # Poly Haven's own .blend materials use for the large majority of the library. # Of the rest the API offers, "arm" is an ORM repacking of maps already here, # "rough_ao" is roughness with AO baked in, and "nor_dx" is the other normal map # convention. "AO", "spec" and "Bump" need extra nodes to be worth anything. # # It is not a complete match for every asset: measured across the 860 published # textures, 114 ship a .blend referencing a map not in this table - 74 use "AO", # and 30 fabrics drive Anisotropic, Anisotropic Rotation and IOR from # "anisotropy_strength", "anisotropy_rotation" and "spec_ior". Those materials # come out flatter here than the artist built them. # # Downloading every map and then leaving most of them unconnected is what cost # 7.4MB to build a 1k material that connected 1.9MB of it. This table brings # that asset down to 3.9MB, all of it wired. POLYHAVEN_TEXTURE_MAPS = { "Diffuse": "base_color", "Rough": "roughness", "Metal": "metallic", "Displacement": "displacement", "nor_gl": "normal", "nor_dx": "normal", } # Only the albedo is colour data; every other map is values the shader reads. POLYHAVEN_COLOR_ROLES = {"base_color"} POLYHAVEN_SLUG_RE = re.compile(r"^[A-Za-z0-9_-]{1,80}$") POLYHAVEN_SITE = "https://polyhaven.com" # `type` is an integer in the API's asset records. POLYHAVEN_ASSET_TYPES = {0: "hdris", 1: "textures", 2: "models"} POLYHAVEN_SEARCH_LIMIT = 20 POLYHAVEN_SEARCH_MAX_LIMIT = 50 # Levels of the category tree returned when every asset type is asked for at # once. Filtering on a category is inclusive, so a parent still selects # everything nested beneath it. POLYHAVEN_TAXONOMY_DEPTH_ALL = 2 # Poly Haven publishes thumbnails at 256px. The CDN resizes from the query # string, so a preview worth looking at costs no stored file. POLYHAVEN_PREVIEW_SIZE = 512 class PolyHavenAPIError(Exception): """A non-2xx from the Poly Haven API, with the status kept. Needed because 429 and 503 want different handling from a generic failure: one means back off, the other means the search index is unavailable and the API is telling us to fall back to matching keywords ourselves. """ def __init__(self, status, retry_after=None): super().__init__(f"HTTP {status}") self.status = status self.retry_after = retry_after # Poly Haven serves the asset list with `Cache-Control: max-age=43200` and an # ETag, and both were being discarded: every search re-fetched all 2.44MB of it. # The TTL here matches theirs, and once it lapses the ETag usually turns the # refetch into a 304. POLYHAVEN_CACHE_TTL = 12 * 60 * 60 # Bounded so a session that searches every type and taxonomy cannot grow without # limit. The asset list is by far the largest entry, and there are four of those. POLYHAVEN_CACHE_MAX_ENTRIES = 16 _polyhaven_cache = {} # A counter rather than a clock. time.time() has ~15ms resolution on Windows, so # entries touched inside one burst of calls tie, and min() then evicts whichever # happens to come first in the dict - which can be the very entry this is # protecting. _polyhaven_cache_clock = 0 def _polyhaven_cache_touch(): global _polyhaven_cache_clock _polyhaven_cache_clock += 1 return _polyhaven_cache_clock def _polyhaven_cache_key(path, params): return path, tuple(sorted((params or {}).items())) def _polyhaven_api_get(path, params=None, cache=False): """GET a Poly Haven API endpoint, raising on anything but a 2xx. With cache=True the response is held for POLYHAVEN_CACHE_TTL, and revalidated with If-None-Match after that rather than re-downloaded. """ key = _polyhaven_cache_key(path, params) entry = _polyhaven_cache.get(key) if cache else None headers = dict(POLYHAVEN_HEADERS) if entry is not None: if time.time() - entry["fetched"] < POLYHAVEN_CACHE_TTL: entry["used"] = _polyhaven_cache_touch() return entry["payload"] if entry.get("etag"): headers["If-None-Match"] = entry["etag"] response = requests.get( f"{POLYHAVEN_API_BASE}/{path}", params=params, headers=headers, timeout=POLYHAVEN_API_TIMEOUT, ) if entry is not None and response.status_code == 304: entry["fetched"] = time.time() entry["used"] = _polyhaven_cache_touch() return entry["payload"] if response.status_code >= 400: raise PolyHavenAPIError( response.status_code, getattr(response, "headers", {}).get("Retry-After"), ) payload = response.json() if cache: if len(_polyhaven_cache) >= POLYHAVEN_CACHE_MAX_ENTRIES: # Least recently USED, not least recently fetched. Evicting on fetch # time is strictly FIFO, because a hit never refreshes it - and the # asset list is by construction the first thing fetched in a session # and then only ever read, so it was always the first entry thrown # out, displaced by one-shot search payloads a tenth of a percent its # size. Its ETag went with it, so the refetch could not revalidate. coldest = min(_polyhaven_cache, key=lambda k: _polyhaven_cache[k]["used"]) _polyhaven_cache.pop(coldest, None) _polyhaven_cache[key] = { "payload": payload, "etag": getattr(response, "headers", {}).get("ETag"), "fetched": time.time(), "used": _polyhaven_cache_touch(), } return payload def _polyhaven_valid_slug(asset_id): """Poly Haven slugs are always [A-Za-z0-9_-]. Asset ids arrive from the model and are used to build the names of the files downloaded into the temporary directory, so they are checked once here rather than escaped differently in each place. """ return bool(POLYHAVEN_SLUG_RE.match(asset_id or "")) def _polyhaven_download(file_info, dest_path): """Stream one file to dest_path, verifying the md5 the API published. Streaming matters: resolution="24k", file_format="exr" is a valid call and that file is 2.4GB, which the previous response.content read materialised in memory in full before writing it back out again. """ expected = file_info.get("md5") response = requests.get( file_info["url"], headers=POLYHAVEN_HEADERS, stream=True, timeout=POLYHAVEN_FILE_TIMEOUT, ) response.raise_for_status() digest = hashlib.md5() with open(dest_path, "wb") as f: for chunk in response.iter_content(chunk_size=POLYHAVEN_CHUNK_SIZE): if not chunk: continue digest.update(chunk) f.write(chunk) if expected and digest.hexdigest() != expected: with suppress(OSError): os.unlink(dest_path) raise ValueError( f"Checksum mismatch for {os.path.basename(dest_path)}: " "the download was truncated or corrupted" ) return dest_path def _polyhaven_uncompress_head(raw): """The start of a .blend, which is usually compressed on disk. Blender wrote gzip up to 2.93 and zstd from 3.0. Both decompressors are incremental, so a truncated prefix decompresses to a shorter prefix rather than raising. """ if raw[:7] == b"BLENDER": return raw if raw[:2] == b"\x1f\x8b": with suppress(Exception): return zlib.decompressobj(16 + zlib.MAX_WBITS).decompress(raw) return None try: import zstandard except ImportError: # Not bundled with every Blender build. Without it the version cannot be # read, and the import falls back to trying the append and handling the # failure - which is the same outcome, one download later. return None with suppress(Exception): return zstandard.ZstdDecompressor().decompressobj().decompress(raw) return None def _polyhaven_blend_version(path): """(major, minor) of the Blender that wrote this .blend, or None. Blender cannot open a file written by a newer version than itself, and Poly Haven's models span 2.93 to 5.0 because each was saved by whichever Blender compiled it. The version is in the file header, in one of two layouts: up to Blender 4.4: BLENDER-v293 from Blender 4.5: BLENDER17-01v0502 where the digits straight after BLENDER are the header's own length, and the version field grows from three characters to four. """ try: with open(path, "rb") as f: head = _polyhaven_uncompress_head(f.read(1 << 16)) except OSError: return None if not head or not head.startswith(b"BLENDER"): return None try: if head[7:9].isdigit(): return int(head[13:15]), int(head[15:17]) return int(head[9:10]), int(head[10:12]) except (ValueError, IndexError): return None def _polyhaven_category_paths(nodes, depth=None, _level=1): """Flatten the category tree to its paths, which is what filters take.""" paths = [] for node in nodes or []: if node.get("path"): paths.append(node["path"]) if depth is None or _level < depth: paths.extend(_polyhaven_category_paths(node.get("children"), depth, _level + 1)) return paths def _polyhaven_taxonomy(asset_type, depth=None): """The category tree and attribute schema for one asset type, trimmed. The raw response is 60-80KB per type, most of it descriptions, UUIDs and URL slugs that nothing here uses. The paths are what a `categories` filter takes, and matching on them is inclusive, so a parent path selects everything beneath it. """ payload = _polyhaven_api_get(f"taxonomy/{quote(asset_type, safe='')}", cache=True) attributes = {} for key, spec in (payload.get("attributes") or {}).items(): if isinstance(spec, dict): attributes[key] = { field: spec[field] for field in ("type", "enum", "description") if field in spec } return { "type": payload.get("type") or asset_type, "categories": _polyhaven_category_paths(payload.get("categories"), depth), "attributes": attributes, } def _polyhaven_asset_url(slug): return f"{POLYHAVEN_SITE}/a/{quote(slug, safe='')}" def _polyhaven_asset_record(slug): """One asset's metadata, taken from the cached asset list where possible. /info/{id} is the same record plus a few internal fields, so it is only worth a request when the list has not already been fetched. """ for entry in _polyhaven_cache.values(): payload = entry.get("payload") if isinstance(payload, dict): record = payload.get(slug) if isinstance(record, dict) and "name" in record: return record return _polyhaven_api_get(f"info/{quote(slug, safe='')}", cache=True) def _polyhaven_preview_url(thumbnail_url, size=POLYHAVEN_PREVIEW_SIZE): """Resize the published thumbnail without losing its cache-busting `v`. Poly Haven's CDN resizes from the query string, so a larger preview costs no stored file - but `thumbnail_url` also carries a `v` holding a hash of the asset's images, and a URL rebuilt by hand without it can be served a year-old thumbnail for an asset whose renders have since been replaced. """ parts = urlparse(thumbnail_url) params = dict(parse_qsl(parts.query, keep_blank_values=True)) if "width" in params or "height" in params: params["width"] = str(size) params["height"] = str(size) return urlunparse(parts._replace(query=urlencode(params))) def _polyhaven_summarize_asset(slug, record): """Trim an /assets record down to what is worth sending back over MCP. The full record is around a kilobyte of JSON per asset and the whole page of results crosses the socket in one message, so twenty untrimmed records is most of what the model then has to read. """ authors = record.get("authors") or {} summary = { "id": slug, "name": record.get("name") or slug, "type": POLYHAVEN_ASSET_TYPES.get(record.get("type"), "unknown"), "url": _polyhaven_asset_url(slug), "authors": sorted(authors) if isinstance(authors, dict) else authors, "downloads": record.get("download_count"), } for key in ("description", "category", "tags", "attributes", "max_resolution", "thumbnail_url"): value = record.get(key) if value: summary[key] = value # Real-world size in millimetres, published for every texture. Without it # there is no way to know that a wall texture is 1.8m across, and the # material gets whatever tiling the object's UVs happen to give it. if record.get("dimensions"): summary["dimensions_mm"] = record["dimensions"] return summary def _polyhaven_search(query, asset_type): """The full ranked list of slugs from Poly Haven's search endpoint. The array order IS the ranking - it fuses a vector lane and a keyword lane by position - so it must not be re-sorted by `score`, which reports vector similarity alone. No `limit` is sent. The endpoint returns the whole ranked list by design, because callers are expected to intersect it with whatever they already hold; asking for the first N and then filtering those would drop matches that were simply further down. """ params = {"q": query} if asset_type and asset_type != "all": params["t"] = asset_type payload = _polyhaven_api_get("search", params=params, cache=True) return [r["slug"] for r in (payload.get("results") or []) if r.get("slug")] def _polyhaven_keyword_match(query, assets): """The fallback the API asks for when it answers a search with 503.""" terms = [term for term in query.split() if term] scored = [] for slug, record in assets.items(): haystack = " ".join([ slug.replace("_", " "), str(record.get("name") or ""), " ".join(record.get("tags") or []), str(record.get("category") or ""), ]).lower() hits = sum(1 for term in terms if term in haystack) if hits: scored.append((hits, record.get("download_count", 0), slug)) scored.sort(reverse=True) return [slug for _hits, _downloads, slug in scored] def _polyhaven_resolution_rank(resolution): """"4k" -> 4, so resolutions sort numerically rather than as strings.""" try: return int(str(resolution).rstrip("k")) except (TypeError, ValueError): return -1 def _polyhaven_sorted_resolutions(resolutions): return sorted(resolutions, key=lambda res: (_polyhaven_resolution_rank(res) < 0, _polyhaven_resolution_rank(res))) def _polyhaven_available(files_data, asset_type): """Describe what an asset actually offers, for use in error messages. The three "not available" errors this replaces were f-strings with nothing interpolated into them, so an agent that guessed a resolution wrong had no way to correct itself except to guess again - and each guess cost another round trip. """ supported = POLYHAVEN_SUPPORTED_FORMATS.get(asset_type, ()) resolutions, formats = set(), set() for by_resolution in files_data.values(): if not isinstance(by_resolution, dict): continue for resolution, by_format in by_resolution.items(): if not isinstance(by_format, dict): continue present = {fmt for fmt in by_format if fmt in supported} if present: resolutions.add(resolution) formats |= present return ( "available resolutions: " + (", ".join(_polyhaven_sorted_resolutions(resolutions)) or "none") + "; formats: " + (", ".join(sorted(formats)) or "none") ) def _polyhaven_select_texture_maps(files_data, resolution, file_format): """The map keys worth downloading, in the order they should be laid out.""" selected = {} for key, role in POLYHAVEN_TEXTURE_MAPS.items(): by_resolution = files_data.get(key) if not isinstance(by_resolution, dict): continue if file_format in by_resolution.get(resolution, {}): selected[key] = role # OpenGL-convention normals are what Blender's Normal Map node expects. # nor_dx is the same map with the green channel flipped, and is only worth # fetching for the few assets that ship no nor_gl. if "nor_gl" in selected: selected.pop("nor_dx", None) # A handful of textures name their albedo something other than "Diffuse" - # the multi-variant fabrics ship col_1/col_2/col_03 instead of one map. # Taking the first is a guess, but a material with no base colour at all is # the failure this whole table exists to prevent. if "base_color" not in selected.values(): for key in sorted(files_data): if not key.lower().startswith(("col", "diff")): continue by_resolution = files_data.get(key) if isinstance(by_resolution, dict) and file_format in by_resolution.get(resolution, {}): selected[key] = "base_color" break return selected def _polyhaven_set_colorspace(image, is_color_data): """Set a colorspace that exists on this Blender build. The names moved around in 4.0, so each candidate is tried in turn rather than assuming any one of them is present. """ candidates = ("sRGB",) if is_color_data else ("Non-Color", "Linear Rec.709", "Linear") for name in candidates: try: image.colorspace_settings.name = name return name except Exception: continue return image.colorspace_settings.name def _polyhaven_authors(asset_id): """Author names for an asset. Best effort - never fails an import.""" with suppress(Exception): record = _polyhaven_asset_record(asset_id) authors = record.get("authors") or {} return sorted(authors) if isinstance(authors, dict) else list(authors) return [] def _polyhaven_dimensions_mm(asset_id): """A texture's real-world size in millimetres. Best effort, like the authors. Read from the record _polyhaven_authors has already fetched, so it costs no extra request. Length two means a texture: a model's `dimensions` is a bounding box, which is a different measurement and is readable from the object itself once it is in the scene. """ with suppress(Exception): dimensions = _polyhaven_asset_record(asset_id).get("dimensions") if isinstance(dimensions, (list, tuple)) and len(dimensions) == 2: return [float(value) for value in dimensions] return None def _polyhaven_mapping_node(node_tree): """The node every image node's Vector input is routed through, if it is still there.""" with suppress(Exception): for node in node_tree.nodes: if node.type == 'MAPPING': return node return None def _polyhaven_tag(datablocks, asset_id, resolution=None, authors=None, dimensions=None): """Record where a datablock came from, in the file that keeps it. Two jobs. It is the lookup key between downloading a texture and applying it - the old code recovered the map type by parsing the image's name, taking the last underscore-separated token, which turned "nor_gl" into "gl" and left the download path and set_texture disagreeing about what a map was called. It is also where the asset came from, in the same shape the Poly Pizza integration writes its polypizza_* properties. Poly Haven's assets are CC0 and require no attribution, ever - but custom properties are saved into the .blend, so whoever opens the file in a year can still find the asset's page, who made it, and the resolutions they did not download. """ for block in datablocks: if block is None: continue with suppress(Exception): block["polyhaven_id"] = asset_id block["polyhaven_url"] = _polyhaven_asset_url(asset_id) block["polyhaven_licence"] = "CC0" if resolution: block["polyhaven_resolution"] = resolution if authors: block["polyhaven_authors"] = ", ".join(authors) elif "polyhaven_authors" in block.keys(): # The lookup is best-effort and comes back empty on any API # failure. Every other field is overwritten regardless, so # leaving a previous asset's artist behind on a datablock that # is being re-tagged would credit them for somebody else's work. del block["polyhaven_authors"] # The texture's real-world size, the same measurement Poly Haven's # own add-on writes onto the materials it ships. Saved into the # .blend because tiling cannot be worked out without it and it is # otherwise visible exactly once, in a search result. if dimensions: block["polyhaven_scale_mm"] = list(dimensions) elif "polyhaven_scale_mm" in block.keys(): del block["polyhaven_scale_mm"] #endregion #region Manual edit capture # Records what the human does in Blender while an MCP session is live. MAX_EDIT_EVENTS = 256 # Operators that fire constantly during interactive work and carry no meaningful # intent on their own. _IGNORED_OPERATORS = frozenset({ "view3d.rotate", "view3d.move", "view3d.zoom", "view3d.dolly", "view3d.view_axis", "view3d.view_orbit", "view3d.view_pan", "view3d.smoothview", "view3d.cursor3d", "wm.tool_set_by_id", "wm.context_set_value", "screen.animation_step", }) # Operator properties holding filesystem paths. Never recorded. _PATH_PROPERTY_NAMES = frozenset({ "filepath", "filename", "directory", "filepath_raw", "relpath", }) _PATH_PROPERTY_SUBSTRINGS = ("filepath", "filename", "directory", "_dir", "path") MAX_OPERATOR_PROPERTY_CHARS = 200 # depsgraph_update_post fires on every scene update, many times per second # during interactive drags. EDIT_POLL_MIN_INTERVAL = 0.1 def _is_path_property(identifier): """True if an operator property likely holds a filesystem path.""" lowered = identifier.lower() if lowered in _PATH_PROPERTY_NAMES: return True return any(token in lowered for token in _PATH_PROPERTY_SUBSTRINGS) class UserEditRecorder: """Buffers human-originated operator and undo events for the MCP server. Anything that happens while an agent command is running is attributed to the agent, not the human; `agent_command()` brackets that window. """ def __init__(self): self._events = deque(maxlen=MAX_EDIT_EVENTS) self._agent_depth = 0 self._last_operator_count = 0 self._seen_baseline = False self._last_poll_time = 0.0 @contextmanager def agent_command(self): """Suppress capture for the duration of an agent-issued command.""" self._agent_depth += 1 try: yield finally: self._agent_depth = max(0, self._agent_depth - 1) self._resync_operator_baseline() @property def _suppressed(self): return self._agent_depth > 0 def _operator_stack(self): try: return list(bpy.context.window_manager.operators) except Exception: return [] def _resync_operator_baseline(self): self._last_operator_count = len(self._operator_stack()) self._seen_baseline = True def poll_operators(self, now=None): """Emit rows for operators run since the last poll. Main thread only. Throttled to EDIT_POLL_MIN_INTERVAL. """ if self._suppressed: return now = time.time() if now is None else now if (now - self._last_poll_time) < EDIT_POLL_MIN_INTERVAL: return self._last_poll_time = now stack = self._operator_stack() count = len(stack) # First poll only establishes a baseline. if not self._seen_baseline: self._last_operator_count = count self._seen_baseline = True return if count <= self._last_operator_count: # Unchanged, or shrank because of an undo. Hold the high-water # mark so a later redo does not replay emitted operators. return for op in stack[self._last_operator_count:count]: self._record_operator(op) self._last_operator_count = count def _record_operator(self, op): try: bl_idname = getattr(op, "bl_idname", None) if not bl_idname: return # bl_idname is UPPER_CASE_OT_form; normalise to bpy.ops form. normalized = bl_idname.lower().replace("_ot_", ".", 1) if normalized in _IGNORED_OPERATORS: return self._events.append({ "kind": "operator", "bl_idname": normalized, "name": getattr(op, "name", None), "properties": self._operator_properties(op), "timestamp": time.time(), }) except Exception as e: print(f"Manual edit capture: failed to record operator: {e}") @staticmethod def _operator_properties(op): """Best-effort scalar snapshot of an operator's resolved properties.""" props = {} try: rna_props = op.properties.bl_rna.properties except Exception: return props for prop in rna_props: if prop.identifier == "rna_type": continue if _is_path_property(prop.identifier): continue try: value = getattr(op.properties, prop.identifier) except Exception: continue if isinstance(value, str): props[prop.identifier] = value[:MAX_OPERATOR_PROPERTY_CHARS] elif isinstance(value, (bool, int, float)): props[prop.identifier] = value elif hasattr(value, "__len__") and not isinstance(value, (dict, bytes)): try: items = [ v[:MAX_OPERATOR_PROPERTY_CHARS] if isinstance(v, str) else v for v in value if isinstance(v, (bool, int, float, str)) ] if items and len(items) <= 16: props[prop.identifier] = items except Exception: continue return props def record_undo(self, kind): """Record an undo/redo. This is the strongest rejection signal we get.""" if self._suppressed: return self._events.append({ "kind": kind, "timestamp": time.time(), }) # Keep the high-water mark so a redo does not re-emit consumed entries. self._last_operator_count = max( self._last_operator_count, len(self._operator_stack()) ) self._seen_baseline = True def drain(self): """Hand buffered events to the MCP server and clear them.""" events = list(self._events) self._events.clear() return events _edit_recorder = UserEditRecorder() def get_edit_recorder(): return _edit_recorder @persistent def _blendermcp_undo_post(scene, depsgraph=None): _edit_recorder.record_undo("undo") @persistent def _blendermcp_redo_post(scene, depsgraph=None): _edit_recorder.record_undo("redo") @persistent def _blendermcp_depsgraph_post(scene, depsgraph=None): _edit_recorder.poll_operators() def _telemetry_consent_enabled(): """Read the consent preference directly. Fails closed.""" try: addon_prefs = bpy.context.preferences.addons.get(__name__) if not addon_prefs: return False return bool(addon_prefs.preferences.telemetry_consent) except Exception: return False def _register_edit_capture_handlers(): """Attach manual-edit handlers, but only with telemetry consent.""" if not _telemetry_consent_enabled(): _unregister_edit_capture_handlers() return False handlers = [ (bpy.app.handlers.undo_post, _blendermcp_undo_post), (bpy.app.handlers.redo_post, _blendermcp_redo_post), (bpy.app.handlers.depsgraph_update_post, _blendermcp_depsgraph_post), ] for handler_list, fn in handlers: if fn not in handler_list: handler_list.append(fn) return True def sync_edit_capture_handlers(): """Re-apply the consent gate. Safe to call when consent or server state changes.""" try: server_running = bool( getattr(bpy.types, "blendermcp_server", None) and bpy.types.blendermcp_server.running ) except Exception: server_running = False if not server_running: _unregister_edit_capture_handlers() return False return _register_edit_capture_handlers() def _unregister_edit_capture_handlers(): handlers = [ (bpy.app.handlers.undo_post, _blendermcp_undo_post), (bpy.app.handlers.redo_post, _blendermcp_redo_post), (bpy.app.handlers.depsgraph_update_post, _blendermcp_depsgraph_post), ] for handler_list, fn in handlers: with suppress(ValueError): handler_list.remove(fn) #endregion def get_blendermcp_addon_preferences(context=None): """Get add-on preferences object if available.""" if context is None: context = bpy.context addon = context.preferences.addons.get(__name__) return addon.preferences if addon else None def tripo_endpoints(context=None, preferences=None): """Resolve the same domain for the sidebar, developer links and API calls.""" context = context or bpy.context prefs = preferences if preferences is not None else get_blendermcp_addon_preferences(context) domain = (getattr(prefs, "tripo_domain", "ai") if prefs is not None else getattr(context.scene, "blendermcp_tripo_domain", "ai")) domain = domain if domain in ("ai", "com") else "ai" portal = f"https://developers.tripo3d.{domain}/{'zh' if domain == 'com' else 'en'}" return { "domain": domain, "api": f"https://openapi.tripo3d.{domain}/v3", "keys": f"{portal}/keys", } # Tencent Cloud exposes Hunyuan-to-3D through two different services depending on where the # account was created. Mainland accounts (cloud.tencent.com) use the AI3D 3.0 API. Tencent Cloud # International accounts (tencentcloud.com) use the "Hunyuan-to-3D (Professional)" service on the # older hunyuan API in ap-singapore; it rejects the mainland body fields and expects EnablePBR. # Sending International credentials to the mainland endpoint fails with # AuthFailure.SignatureFailure / ResourceUnavailable. HUNYUAN_API_PROFILES = { "mainland": { "service": "ai3d", "version": "2025-05-13", "region": "ap-guangzhou", "submit_action": "SubmitHunyuanTo3DProJob", "query_action": "QueryHunyuanTo3DProJob", "submit_body": {}, }, "international_pro": { "service": "hunyuan", "version": "2023-09-01", "region": "ap-singapore", "submit_action": "SubmitHunyuanTo3DProJob", "query_action": "QueryHunyuanTo3DProJob", "submit_body": {"EnablePBR": True}, }, } def hunyuan_api_profile(international_pro: bool) -> dict: """Return a copy of the Tencent Cloud API profile for the selected account type.""" profile = HUNYUAN_API_PROFILES["international_pro" if international_pro else "mainland"] return {**profile, "submit_body": dict(profile["submit_body"])} # Object types with no surface for a ray to hit, picked by their origin instead. _PICK_BY_ORIGIN = {"LIGHT", "CAMERA", "EMPTY", "LIGHT_PROBE", "SPEAKER", "FORCE_FIELD"} # How close, in image pixels, a click must land to one of those origins. _PICK_RADIUS_PX = 16 def _object_detail(obj): """'Mesh object in collection 'Props'', as mentions and viewport picks show it.""" detail = f"{obj.type.title()} object" if obj.users_collection: detail += f" in collection '{obj.users_collection[0].name}'" return detail class BlenderMCPServer: def __init__(self, host='localhost', port=9876): self.host = host self.port = port self.running = False self.socket = None self.server_thread = None # Commands are pushed here by client threads and drained by a single # timer running on Blender's main thread. bpy.app.timers is not # thread-safe, so registering a timer per command (the previous # approach) could silently drop the callback - on Windows especially - # leaving the client blocked in recv() until its socket timeout. self.command_queue = queue.Queue() # Live client sockets, so stop() can unblock threads parked in recv(). self._clients = set() self._clients_lock = threading.Lock() def _get_config_value(self, scene_attr, pref_attr=None, env_var=None): """Read config in order: addon preferences -> scene -> env var.""" prefs = get_blendermcp_addon_preferences() if prefs and pref_attr: pref_value = getattr(prefs, pref_attr, "") if pref_value: return pref_value scene_value = getattr(bpy.context.scene, scene_attr, "") if scene_value: return scene_value if env_var: env_value = os.getenv(env_var, "") if env_value: return env_value return "" def _get_hyper3d_api_key(self): # The trial key is only valid on the main site. Keep a session trial # override from masking a saved private fal.ai key after switching modes. main_site = bpy.context.scene.blendermcp_hyper3d_mode == 'MAIN_SITE' scene_value = getattr(bpy.context.scene, "blendermcp_hyper3d_api_key", "") if main_site and scene_value == RODIN_FREE_TRIAL_KEY: return scene_value api_key = self._get_config_value( "blendermcp_hyper3d_api_key", "hyper3d_api_key", "BLENDERMCP_HYPER3D_API_KEY", ) if not main_site and api_key == RODIN_FREE_TRIAL_KEY: return "" return api_key def _get_sketchfab_api_key(self): return self._get_config_value( "blendermcp_sketchfab_api_key", "sketchfab_api_key", "BLENDERMCP_SKETCHFAB_API_KEY", ) def _get_polypizza_api_key(self): return self._get_config_value( "blendermcp_polypizza_api_key", "polypizza_api_key", "BLENDERMCP_POLYPIZZA_API_KEY", ) def _get_hunyuan3d_secret_id(self): return self._get_config_value( "blendermcp_hunyuan3d_secret_id", "hunyuan3d_secret_id", "BLENDERMCP_HUNYUAN3D_SECRET_ID", ) def _get_hunyuan3d_secret_key(self): return self._get_config_value( "blendermcp_hunyuan3d_secret_key", "hunyuan3d_secret_key", "BLENDERMCP_HUNYUAN3D_SECRET_KEY", ) def _get_hunyuan3d_api_url(self): return self._get_config_value( "blendermcp_hunyuan3d_api_url", "hunyuan3d_api_url", "BLENDERMCP_HUNYUAN3D_API_URL", ) or "http://localhost:8081" def _get_meshy_api_key(self): return self._get_config_value( "blendermcp_meshy_api_key", "meshy_api_key", "BLENDERMCP_MESHY_API_KEY", ) def _resolve_meshy_model(self): model = getattr(bpy.context.scene, "blendermcp_meshy_model", MESHY_DEFAULT_MODEL) or MESHY_DEFAULT_MODEL if model not in MESHY_MODELS: return None, {"error": f"Unknown Meshy model. Choose one of: {', '.join(MESHY_MODELS)}"} return model, None def _get_worldlabs_api_key(self): return self._get_config_value( "blendermcp_worldlabs_api_key", "worldlabs_api_key", "BLENDERMCP_WORLDLABS_API_KEY", ) def _resolve_worldlabs_model(self): """The sidebar's model. One no longer offered (the draft model, saved in an older file) falls back to the default.""" model = getattr(bpy.context.scene, "blendermcp_worldlabs_model", WORLDLABS_DEFAULT_MODEL) return (model if model in WORLDLABS_MODELS else WORLDLABS_DEFAULT_MODEL), None def _get_tripo_api_key(self): return self._get_config_value( "blendermcp_tripo_api_key", "tripo_api_key", "BLENDERMCP_TRIPO_API_KEY", ) def _resolve_tripo_model(self): model = getattr(bpy.context.scene, "blendermcp_tripo_model", TRIPO_DEFAULT_MODEL) or TRIPO_DEFAULT_MODEL if model not in TRIPO_MODELS: return None, {"error": f"Unknown Tripo model. Choose one of: {', '.join(TRIPO_MODELS)}"} return model, None def start(self): if bpy.app.background: print("BlenderMCP: cannot start server in background mode (blender -b) - commands would never execute\n" "BlenderMCP: run Blender with a GUI, or use a virtual display: xvfb-run -a blender") return if self.running: print("Server is already running") return self.running = True try: # Create socket self.socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) self.socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) self.socket.bind((self.host, self.port)) # Backlog of 1 meant a reconnecting client could complete the TCP # handshake and then never be accept()ed - a connection that looks # established but is never serviced. self.socket.listen(5) # Start server thread self.server_thread = threading.Thread(target=self._server_loop) self.server_thread.daemon = True self.server_thread.start() _register_edit_capture_handlers() # start() is called from the operator, i.e. the main thread, so # this is the only safe place to touch bpy.app.timers. if not bpy.app.timers.is_registered(self._drain_command_queue): bpy.app.timers.register(self._drain_command_queue, persistent=True) print(f"BlenderMCP server started on {self.host}:{self.port}") except Exception as e: print(f"Failed to start server: {str(e)}") self.stop() def stop(self): self.running = False _unregister_edit_capture_handlers() get_edit_recorder().drain() try: if bpy.app.timers.is_registered(self._drain_command_queue): bpy.app.timers.unregister(self._drain_command_queue) except Exception: pass # Close socket if self.socket: try: self.socket.close() except: pass self.socket = None # Shut down live client sockets. Without this, handler threads stay # parked in a blocking recv() forever; being daemon threads they then # outlive the restart and close connections the new server owns # (the WinError 10054 seen after toggling the addon). with self._clients_lock: clients = list(self._clients) self._clients.clear() for client in clients: try: client.shutdown(socket.SHUT_RDWR) except Exception: pass try: client.close() except Exception: pass # Drop any commands that will never be serviced now. while True: try: self.command_queue.get_nowait() except queue.Empty: break # Wait for thread to finish if self.server_thread: try: if self.server_thread.is_alive(): self.server_thread.join(timeout=1.0) except: pass self.server_thread = None print("BlenderMCP server stopped") def _server_loop(self): """Main server loop in a separate thread""" print("Server thread started") self.socket.settimeout(1.0) # Timeout to allow for stopping while self.running: try: # Accept new connection try: client, address = self.socket.accept() print(f"Connected to client: {address}") # Handle client in a separate thread client_thread = threading.Thread( target=self._handle_client, args=(client,) ) client_thread.daemon = True client_thread.start() except socket.timeout: # Just check running condition continue except Exception as e: print(f"Error accepting connection: {str(e)}") time.sleep(0.5) except Exception as e: print(f"Error in server loop: {str(e)}") if not self.running: break time.sleep(0.5) print("Server thread stopped") def _drain_command_queue(self): """Run queued commands on Blender's main thread. Registered once by start(); returns the poll interval so Blender keeps calling it. All bpy access happens here, on the main thread. """ if not self.running: return None while True: try: command, client = self.command_queue.get_nowait() except queue.Empty: break # A client that gave up while an earlier command held the main # thread (a long import or boolean) isn't waiting for this one. # Running it anyway kept Blender busy with abandoned retries long # after the long command finished (#430). if self._client_gone(client): print(f"Skipped command {command.get('type')}: client disconnected before it ran") continue try: response = self.execute_command(command) response_json = json.dumps(response) except Exception as e: print(f"Error executing command: {str(e)}") traceback.print_exc() response_json = json.dumps({"status": "error", "message": str(e)}) try: client.sendall(response_json.encode('utf-8')) except Exception: print("Failed to send response - client disconnected") return 0.05 def _client_gone(self, client): """True if the client hung up. Never blocks and never consumes data.""" with self._clients_lock: if client not in self._clients: return True try: readable, _, _ = select.select([client], [], [], 0) # Readable with nothing to peek at means the peer closed. return bool(readable) and client.recv(1, socket.MSG_PEEK) == b'' except socket.timeout: # Its handler thread read the pending data first; still connected. return False except (OSError, ValueError): return True def _handle_client(self, client): """Handle connected client""" print("Client handler started") # A finite timeout keeps this loop responsive to self.running instead # of parking in recv() forever. client.settimeout(1.0) with self._clients_lock: self._clients.add(client) buffer = b'' try: while self.running: # Receive data try: data = client.recv(8192) if not data: print("Client disconnected") break buffer += data try: # Try to parse command command = json.loads(buffer.decode('utf-8')) buffer = b'' # Hand off to the main thread. Never call # bpy.app.timers.register() from here - it is not # thread-safe and the callback can be silently lost. print(f"Queued command: {command.get('type')}") self.command_queue.put((command, client)) except (json.JSONDecodeError, UnicodeDecodeError): # Incomplete data, wait for more. A multi-byte UTF-8 # character can land split across a recv() chunk # boundary, which fails decode() before json.loads() # ever runs - that's incomplete data too, not garbage. pass except socket.timeout: # Expected; loop round and re-check self.running. continue except Exception as e: print(f"Error receiving data: {str(e)}") break except Exception as e: print(f"Error in client handler: {str(e)}") finally: with self._clients_lock: self._clients.discard(client) try: client.close() except: pass print("Client handler stopped") def execute_command(self, command): """Execute a command in the main Blender thread""" try: with get_edit_recorder().agent_command(): return self._execute_command_internal(command) except Exception as e: print(f"Error executing command: {str(e)}") traceback.print_exc() return {"status": "error", "message": str(e)} def _execute_command_internal(self, command): """Internal command execution with proper context""" cmd_type = command.get("type") params = command.get("params", {}) # Trivial liveness check. Touches no bpy data, so a successful ping # alongside a failing command isolates data access from transport. if cmd_type == "ping": return {"status": "success", "result": {"pong": True}} # Add a handler for checking PolyHaven status if cmd_type == "get_polyhaven_status": return {"status": "success", "result": self.get_polyhaven_status()} # Base handlers that are always available handlers = { "get_scene_info": self.get_scene_info, "get_world_state_snapshot": self.get_world_state_snapshot, "get_addon_info": self.get_addon_info, "get_object_info": self.get_object_info, "list_scene_items": self.list_scene_items, "get_viewport_screenshot": self.get_viewport_screenshot, "pick_viewport_object": self.pick_viewport_object, "execute_code": self.execute_code, "describe_node_type": self.describe_node_type, "bpy_api_lookup": self.bpy_api_lookup, "drain_human_activity": self.drain_human_activity, "get_telemetry_consent": self.get_telemetry_consent, "set_telemetry_consent": self.set_telemetry_consent, "get_polyhaven_status": self.get_polyhaven_status, "get_hyper3d_status": self.get_hyper3d_status, "get_sketchfab_status": self.get_sketchfab_status, "get_polypizza_status": self.get_polypizza_status, "get_hunyuan3d_status": self.get_hunyuan3d_status, "get_tripo_status": self.get_tripo_status, "get_meshy_status": self.get_meshy_status, "get_worldlabs_status": self.get_worldlabs_status, "export_scene": self.export_scene, } # Add Polyhaven handlers only if enabled if bpy.context.scene.blendermcp_use_polyhaven: polyhaven_handlers = { "get_polyhaven_categories": self.get_polyhaven_categories, "search_polyhaven_assets": self.search_polyhaven_assets, "download_polyhaven_asset": self.download_polyhaven_asset, "get_polyhaven_asset_preview": self.get_polyhaven_asset_preview, "set_texture": self.set_texture, } handlers.update(polyhaven_handlers) # Add Hyper3d handlers only if enabled if bpy.context.scene.blendermcp_use_hyper3d: polyhaven_handlers = { "create_rodin_job": self.create_rodin_job, "poll_rodin_job_status": self.poll_rodin_job_status, "import_generated_asset": self.import_generated_asset, } handlers.update(polyhaven_handlers) # Add Sketchfab handlers only if enabled if bpy.context.scene.blendermcp_use_sketchfab: sketchfab_handlers = { "search_sketchfab_models": self.search_sketchfab_models, "get_sketchfab_model_preview": self.get_sketchfab_model_preview, "download_sketchfab_model": self.download_sketchfab_model, } handlers.update(sketchfab_handlers) # Add Poly Pizza handlers only if enabled if bpy.context.scene.blendermcp_use_polypizza: polypizza_handlers = { "search_polypizza_models": self.search_polypizza_models, "download_polypizza_model": self.download_polypizza_model, } handlers.update(polypizza_handlers) # Add Hunyuan3d handlers only if enabled if bpy.context.scene.blendermcp_use_hunyuan3d: hunyuan_handlers = { "create_hunyuan_job": self.create_hunyuan_job, "poll_hunyuan_job_status": self.poll_hunyuan_job_status, "import_generated_asset_hunyuan": self.import_generated_asset_hunyuan } handlers.update(hunyuan_handlers) # Tripo runs through Premium when it's the generation source, else on # the user's own key. getattr so scenes from before Tripo still dispatch. if getattr(bpy.context.scene, "blendermcp_use_tripo", False) and premium_active(): handlers.update(premium_tripo_handlers()) elif getattr(bpy.context.scene, "blendermcp_use_tripo", False): handlers.update({ "create_tripo_job": self.create_tripo_job, "poll_tripo_job_status": self.poll_tripo_job_status, "import_generated_asset_tripo": self.import_generated_asset_tripo, }) # Meshy runs through Premium when it's the generation source, else on # the user's own key. getattr so scenes from before Meshy still dispatch. if getattr(bpy.context.scene, "blendermcp_use_meshy", False) and premium_active(): handlers.update(premium_meshy_handlers()) elif getattr(bpy.context.scene, "blendermcp_use_meshy", False): handlers.update({ "create_meshy_job": self.create_meshy_job, "refine_meshy_job": self.refine_meshy_job, "poll_meshy_job_status": self.poll_meshy_job_status, "import_generated_asset_meshy": self.import_generated_asset_meshy, }) # World Labs likewise, through Premium or on the user's own key. if getattr(bpy.context.scene, "blendermcp_use_worldlabs", False) and premium_active(): handlers.update(premium_worldlabs_handlers()) elif getattr(bpy.context.scene, "blendermcp_use_worldlabs", False): handlers.update({ "create_worldlabs_job": self.create_worldlabs_job, "poll_worldlabs_job": self.poll_worldlabs_job, "import_worldlabs_world": self.import_worldlabs_world, }) handler = handlers.get(cmd_type) if handler: try: print(f"Executing handler for {cmd_type}") result = handler(**params) print(f"Handler execution complete") return {"status": "success", "result": result} except Exception as e: print(f"Error in handler: {str(e)}") traceback.print_exc() return {"status": "error", "message": str(e)} else: return {"status": "error", "message": f"Unknown command type: {cmd_type}"} def get_addon_info(self): """Version/capability handshake for the MCP server (and install tooling).""" return { "name": bl_info.get("name", "MCP for Blender"), "addon_version": list(bl_info.get("version", (0, 0))), "protocol_version": ADDON_PROTOCOL_VERSION, "capabilities": sorted([ "get_scene_info", "get_world_state_snapshot", "get_addon_info", "get_object_info", "list_scene_items", "get_viewport_screenshot", "pick_viewport_object", "execute_code", "describe_node_type", "bpy_api_lookup", "drain_human_activity", "get_telemetry_consent", "set_telemetry_consent", ]), "blender_version": bpy.app.version_string, "premium_generators": premium_enabled_generators(), } def get_scene_info(self): """Get information about the current Blender scene""" try: print("Getting scene info...") # Simplify the scene info to reduce data size scene_info = { "name": bpy.context.scene.name, "object_count": len(bpy.context.scene.objects), "objects": [], "materials_count": len(bpy.data.materials), } # Collect minimal object information (limit to first 10 objects) for i, obj in enumerate(bpy.context.scene.objects): if i >= 10: # Reduced from 20 to 10 break obj_info = { "name": obj.name, "type": obj.type, # Only include basic location data "location": [round(float(obj.location.x), 2), round(float(obj.location.y), 2), round(float(obj.location.z), 2)], } scene_info["objects"].append(obj_info) print(f"Scene info collected: {len(scene_info['objects'])} objects") return scene_info except Exception as e: print(f"Error in get_scene_info: {str(e)}") traceback.print_exc() return {"error": str(e)} def list_scene_items(self, query="", limit=30): """Objects, materials and collections whose names match `query`. Backs composer @-mentions, which call this on every keystroke, so it reads names and cheap counts only. Name matches that start with the query rank before ones that merely contain it. """ needle = (query or "").strip().lower() limit = max(1, min(int(limit or 30), 100)) material_users = {} for obj in bpy.context.scene.objects: for slot in getattr(obj, "material_slots", None) or []: if slot.material: material_users.setdefault(slot.material.name, []).append(obj.name) candidates = [] for obj in bpy.context.scene.objects: candidates.append(("object", obj.name, _object_detail(obj))) for mat in bpy.data.materials: users = material_users.get(mat.name, []) if users: shown = ", ".join(users[:3]) + (f" and {len(users) - 3} more" if len(users) > 3 else "") detail = f"Material on {shown}" else: detail = "Material not used by any object in this scene" candidates.append(("material", mat.name, detail)) for coll in bpy.data.collections: candidates.append(("collection", coll.name, f"Collection with {len(coll.all_objects)} objects")) matches = [] for order, (kind, name, detail) in enumerate(candidates): lowered = name.lower() if needle and needle not in lowered: continue rank = 0 if not needle or lowered.startswith(needle) else 1 matches.append((rank, order, {"kind": kind, "name": name, "detail": detail})) matches.sort(key=lambda m: (m[0], m[1])) return {"items": [m[2] for m in matches[:limit]], "total": len(matches)} def drain_human_activity(self): """Return human-originated events buffered since the last drain. Consent is enforced MCP-side (the server only drains and uploads when the user has opted in), but we also refuse here so a buffer does not accumulate for a user who has said no. """ try: if not self.get_telemetry_consent().get("consent"): get_edit_recorder().drain() return {"events": []} return {"events": get_edit_recorder().drain()} except Exception as e: print(f"Error draining manual edits: {str(e)}") return {"error": str(e)} @staticmethod def _snapshot_geometry(obj): """World-space AABB + dimensions for one object, or None. Without these, downstream analysis cannot compute contact, containment or collision: `scale` alone is a multiplier on unknown base geometry. Uses obj.bound_box (8 cached local corners) rather than mesh vertices, so cost is constant per object regardless of poly count. """ bound_box = getattr(obj, "bound_box", None) if not bound_box: return None try: matrix_world = obj.matrix_world xs, ys, zs = [], [], [] for corner in bound_box: world = matrix_world @ mathutils.Vector(corner) xs.append(world.x) ys.append(world.y) zs.append(world.z) return { "aabb_min": [round(min(xs), 3), round(min(ys), 3), round(min(zs), 3)], "aabb_max": [round(max(xs), 3), round(max(ys), 3), round(max(zs), 3)], "dimensions": [ round(float(obj.dimensions.x), 3), round(float(obj.dimensions.y), 3), round(float(obj.dimensions.z), 3), ], } except Exception: return None @staticmethod def _snapshot_relations(obj): """Parent and constraint targets, so hierarchies read correctly. World `location` alone misreports parented objects, whose authored values are parent-relative. """ relations = {} parent = getattr(obj, "parent", None) if parent: relations["parent"] = parent.name relations["parent_type"] = obj.parent_type loc = obj.matrix_local.translation relations["local_location"] = [ round(float(loc.x), 3), round(float(loc.y), 3), round(float(loc.z), 3), ] constraints = [] for constraint in getattr(obj, "constraints", None) or []: entry = {"type": constraint.type} target = getattr(constraint, "target", None) if target: entry["target"] = target.name constraints.append(entry) if len(constraints) >= 8: break if constraints: relations["constraints"] = constraints modifiers = [m.type for m in (getattr(obj, "modifiers", None) or [])[:8]] if modifiers: relations["modifiers"] = modifiers return relations @staticmethod def _snapshot_animation(obj): """Action name and per-channel keyframe summary for one object, or {}. Static transforms alone cannot distinguish an authored edit from playback landing on a different frame. Reads F-curve metadata (`data_path`, `array_index`, `len(keyframe_points)`) rather than individual keyframes, so cost stays proportional to channel count rather than to animation length. """ try: anim_data = getattr(obj, "animation_data", None) if not anim_data: return {} animation = {} action = getattr(anim_data, "action", None) if action: animation["action"] = action.name channels = [] total_keyframes = 0 frame_min, frame_max = None, None for fcurve in action.fcurves: keyframe_points = fcurve.keyframe_points count = len(keyframe_points) total_keyframes += count if count and len(channels) < 16: channels.append({ "data_path": fcurve.data_path, "array_index": fcurve.array_index, "keyframes": count, }) if count: first = keyframe_points[0].co.x last = keyframe_points[-1].co.x frame_min = first if frame_min is None else min(frame_min, first) frame_max = last if frame_max is None else max(frame_max, last) if channels: animation["channels"] = channels animation["keyframe_count"] = total_keyframes if frame_min is not None: animation["frame_range"] = [round(float(frame_min), 3), round(float(frame_max), 3)] drivers = getattr(anim_data, "drivers", None) if drivers and len(drivers): animation["driver_count"] = len(drivers) nla_tracks = [ track.name for track in (getattr(anim_data, "nla_tracks", None) or [])[:8] ] if nla_tracks: animation["nla_tracks"] = nla_tracks return {"animation": animation} if animation else {} except Exception: return {} @staticmethod def _shader_fingerprint(id_block): """Stable short hash of a node tree (material or world), or None. Node identities plus rounded input values, so tweaking a color or rewiring a link changes the fingerprint. Lets downstream deltas see shader edits that leave every object transform untouched. """ try: if id_block is None: return None tree = id_block.node_tree if getattr(id_block, "use_nodes", False) else None if tree is None: color = getattr(id_block, "diffuse_color", None) or getattr(id_block, "color", None) basis = str([round(float(v), 3) for v in color]) if color is not None else "" else: parts = [] for node in tree.nodes: values = [] for sock in node.inputs: dv = getattr(sock, "default_value", None) if isinstance(dv, (int, float)): values.append(round(float(dv), 3)) elif dv is not None: with suppress(TypeError, ValueError): values.extend(round(float(v), 3) for v in dv) parts.append(f"{node.bl_idname}{values}") parts.sort() parts.append(str(len(tree.links))) basis = "|".join(parts) return format(zlib.crc32(basis.encode("utf-8")), "08x") except Exception: return None @staticmethod def _project_id(): """Salted hash linking sessions on the same .blend without storing its path.""" try: filepath = bpy.data.filepath if not filepath: return None return hashlib.sha256(f"{uuid.getnode()}:{filepath}".encode("utf-8")).hexdigest()[:16] except Exception: return None def get_world_state_snapshot(self): """Compact world-state snapshot for trajectory capture (no mesh/shader detail).""" try: scene = bpy.context.scene selected = [obj.name for obj in bpy.context.selected_objects] selected_count = len(selected) selected_truncated = selected_count > MAX_SNAPSHOT_SELECTED if selected_truncated: # Sorted so before/after snapshots keep the same subset. selected = sorted(selected)[:MAX_SNAPSHOT_SELECTED] objects = [] all_objects = list(scene.objects) truncated = len(all_objects) > MAX_SNAPSHOT_OBJECTS if truncated: # scene.objects iterates in an order that shifts as objects are # created, so an arbitrary prefix would leave the before/after # snapshots of one step holding different subsets and the delta # reporting phantom adds/removes. Sorting keeps them aligned. all_objects = sorted(all_objects, key=lambda o: o.name)[:MAX_SNAPSHOT_OBJECTS] for obj in all_objects: materials = [] if getattr(obj, "material_slots", None): materials = [ slot.material.name for slot in obj.material_slots if slot.material ] entry = { "name": obj.name, "type": obj.type, "location": [ round(float(obj.location.x), 3), round(float(obj.location.y), 3), round(float(obj.location.z), 3), ], "rotation": [ round(float(obj.rotation_euler.x), 3), round(float(obj.rotation_euler.y), 3), round(float(obj.rotation_euler.z), 3), ], "scale": [ round(float(obj.scale.x), 3), round(float(obj.scale.y), 3), round(float(obj.scale.z), 3), ], "visible": bool(obj.visible_get()), "materials": materials, } geometry = self._snapshot_geometry(obj) if geometry: entry.update(geometry) entry.update(self._snapshot_relations(obj)) entry.update(self._snapshot_animation(obj)) data = getattr(obj, "data", None) if obj.type == "MESH" and data is not None: entry["mesh"] = { "vertices": len(data.vertices), "polygons": len(data.polygons), } objects.append(entry) camera = scene.camera camera_info = None if camera: camera_info = { "name": camera.name, "location": [ round(float(camera.location.x), 3), round(float(camera.location.y), 3), round(float(camera.location.z), 3), ], "rotation": [ round(float(camera.rotation_euler.x), 3), round(float(camera.rotation_euler.y), 3), round(float(camera.rotation_euler.z), 3), ], } if camera.type == "CAMERA" and camera.data: camera_info["lens"] = round(float(camera.data.lens), 3) camera_info["sensor_width"] = round(float(camera.data.sensor_width), 3) lights = [] for obj in scene.objects: if obj.type != "LIGHT": continue light_entry = { "name": obj.name, "location": [ round(float(obj.location.x), 3), round(float(obj.location.y), 3), round(float(obj.location.z), 3), ], } if obj.data: light_entry["light_type"] = obj.data.type light_entry["energy"] = round(float(obj.data.energy), 3) lights.append(light_entry) if len(lights) >= 20: break return { "name": scene.name, "object_count": len(scene.objects), # Explicit, so consumers never have to infer truncation from a # hardcoded cap they might disagree with. "objects_listed": len(objects), "objects_truncated": truncated, "selected": selected, "selected_count": selected_count, "selected_truncated": selected_truncated, "frame_current": scene.frame_current, "frame_start": scene.frame_start, "frame_end": scene.frame_end, "fps": round(float(scene.render.fps) / scene.render.fps_base, 3), "objects": objects, "active_camera": camera.name if camera else None, "camera": camera_info, "lights": lights, "materials_count": len(bpy.data.materials), "material_fps": { m.name: self._shader_fingerprint(m) for m in list(bpy.data.materials)[:200] }, "world_fp": self._shader_fingerprint(scene.world), "project_id": self._project_id(), "blender_version": bpy.app.version_string, "snapshot_source": "native", } except Exception as e: print(f"Error in get_world_state_snapshot: {str(e)}") traceback.print_exc() return {"error": str(e)} @staticmethod def _get_aabb(obj): """ Returns the world-space axis-aligned bounding box (AABB) of an object. """ if obj.type != 'MESH': raise TypeError("Object must be a mesh") # Get the bounding box corners in local space local_bbox_corners = [mathutils.Vector(corner) for corner in obj.bound_box] # Convert to world coordinates world_bbox_corners = [obj.matrix_world @ corner for corner in local_bbox_corners] # Compute axis-aligned min/max coordinates min_corner = mathutils.Vector(map(min, zip(*world_bbox_corners))) max_corner = mathutils.Vector(map(max, zip(*world_bbox_corners))) return [ [*min_corner], [*max_corner] ] def get_object_info(self, name): """Get detailed information about a specific object""" obj = bpy.data.objects.get(name) if not obj: raise ValueError(f"Object not found: {name}") # Basic object info obj_info = { "name": obj.name, "type": obj.type, "location": [obj.location.x, obj.location.y, obj.location.z], "rotation": [obj.rotation_euler.x, obj.rotation_euler.y, obj.rotation_euler.z], "scale": [obj.scale.x, obj.scale.y, obj.scale.z], "visible": obj.visible_get(), "materials": [], } if obj.type == "MESH": bounding_box = self._get_aabb(obj) obj_info["world_bounding_box"] = bounding_box # Add material slots for slot in obj.material_slots: if slot.material: obj_info["materials"].append(slot.material.name) # Add mesh data if applicable if obj.type == 'MESH' and obj.data: mesh = obj.data obj_info["mesh"] = { "vertices": len(mesh.vertices), "edges": len(mesh.edges), "polygons": len(mesh.polygons), } return obj_info def get_viewport_screenshot(self, max_size=800, filepath=None, format="png"): """ Capture a screenshot of the current 3D viewport and save it to the specified path. Parameters: - max_size: Maximum size in pixels for the largest dimension of the image - filepath: Path where to save the screenshot file - format: Image format (png, jpg, etc.) Returns success/error status """ # screen.screenshot_area captures the OS window framebuffer, which is # all-black whenever the Blender window is not composited in the # foreground (the normal case when Blender is driven headless-style via # MCP). Render the viewport with gpu.types.GPUOffScreen.draw_view3d # instead, which is independent of window compositing state, and fall # back to the window grab if offscreen rendering is unavailable (e.g. no # GPU context). The response reports which path produced the image. try: if not filepath: return {"error": "No filepath provided"} area = region = space = None for a in bpy.context.screen.areas: if a.type == 'VIEW_3D': area = a space = a.spaces.active region = next((r for r in a.regions if r.type == 'WINDOW'), None) break if not area or region is None or space is None: return {"error": "No 3D viewport found"} method = "offscreen" view = None # Which file and scene this shows, so the app can label it and a # click on it isn't cast into a different one. origin = {"file": bpy.data.filepath, "scene": bpy.context.scene.name} try: import gpu import numpy as np r3d = space.region_3d src_w, src_h = region.width, region.height if max(src_w, src_h) > max_size: s = max_size / max(src_w, src_h) width, height = max(1, int(src_w * s)), max(1, int(src_h * s)) else: width, height = src_w, src_h offscreen = gpu.types.GPUOffScreen(width, height) try: offscreen.draw_view3d( bpy.context.scene, bpy.context.view_layer, space, region, r3d.view_matrix, r3d.window_matrix, do_color_management=True, ) buf = offscreen.texture_color.read() finally: offscreen.free() buf.dimensions = width * height * 4 pixels = np.asarray(buf, dtype=np.float32) / 255.0 # GPU buffer is 0..255 image = bpy.data.images.new("mcp_viewport", width, height, alpha=True) image.pixels.foreach_set(pixels.ravel()) image.filepath_raw = filepath image.file_format = format.upper() image.save() bpy.data.images.remove(image) # The camera this image was drawn with, so a click on it can # be turned back into a ray (pick_viewport_object). view = { **origin, "view_matrix": [list(row) for row in r3d.view_matrix], "window_matrix": [list(row) for row in r3d.window_matrix], "width": width, "height": height, } except Exception as offscreen_err: print(f"[BlenderMCP] offscreen capture failed ({offscreen_err}); " "falling back to window grab", flush=True) method = "window_grab" with bpy.context.temp_override(area=area): bpy.ops.screen.screenshot_area(filepath=filepath) img = bpy.data.images.load(filepath) width, height = img.size if max(width, height) > max_size: s = max_size / max(width, height) width, height = int(width * s), int(height * s) img.scale(width, height) img.file_format = format.upper() img.save() bpy.data.images.remove(img) result = { "success": True, "width": width, "height": height, "filepath": filepath, "method": method, **origin, "scene_count": len(bpy.data.scenes), } if view: result["view"] = view return result except Exception as e: return {"error": str(e)} def pick_viewport_object(self, view_matrix, window_matrix, width, height, x, y, file=None, scene=None): """The object under a click on a viewport capture. The matrices are the ones the capture was drawn with, and x, y run 0..1 from the image's top-left, so this works after the view has moved. Meshes are hit by a ray; lights, cameras and empties have no surface, so they're picked when the click lands near their origin on screen. `file` and `scene` are where the capture came from: a click is only cast into that same scene, never into whatever is open now. """ from mathutils import Matrix, Vector if file is not None and file != bpy.data.filepath: return {"object": None, "mismatch": "file", "current": bpy.data.filepath} if scene is not None and scene != bpy.context.scene.name: return {"object": None, "mismatch": "scene", "current": bpy.context.scene.name} scene = bpy.context.scene projection = Matrix(window_matrix) @ Matrix(view_matrix) unproject = projection.inverted() ndc_x, ndc_y = 2.0 * float(x) - 1.0, 1.0 - 2.0 * float(y) def at_depth(z): p = unproject @ Vector((ndc_x, ndc_y, z, 1.0)) return p.xyz / p.w origin = at_depth(-1.0) direction = (at_depth(1.0) - origin).normalized() picked, picked_depth = None, float("inf") hit, location, _normal, _index, hit_obj, _matrix = scene.ray_cast( bpy.context.evaluated_depsgraph_get(), origin, direction) if hit and hit_obj is not None: picked = getattr(hit_obj, "original", hit_obj) picked_depth = (location - origin).length click_x, click_y = float(x) * width, float(y) * height nearest = _PICK_RADIUS_PX for obj in scene.objects: if obj.type not in _PICK_BY_ORIGIN or not obj.visible_get(): continue p = projection @ obj.matrix_world.translation.to_4d() if p.w <= 0: continue # behind the camera screen_x = (p.x / p.w + 1.0) / 2.0 * width screen_y = (1.0 - p.y / p.w) / 2.0 * height distance = ((screen_x - click_x) ** 2 + (screen_y - click_y) ** 2) ** 0.5 depth = (obj.matrix_world.translation - origin).length # An origin in front of the hit surface wins, as it's drawn on top. if distance <= nearest and depth < picked_depth: picked, nearest = obj, distance if picked is None: return {"object": None} return {"object": { "name": picked.name, "type": picked.type, "detail": _object_detail(picked), "location": list(picked.matrix_world.translation), }} def execute_code(self, code): """Execute arbitrary Blender Python code""" # This is powerful but potentially dangerous - use with caution try: # Create a local namespace for execution namespace = {"bpy": bpy} # Capture stdout during execution, and return it as result capture_buffer = io.StringIO() with redirect_stdout(capture_buffer): exec(code, namespace) captured_output = capture_buffer.getvalue() return {"executed": True, "result": captured_output} except Exception as e: # Give the caller the same detail we have: exception type, message, # and a full traceback (with line numbers into the submitted code), # instead of collapsing everything into one string. Callers that ran # a multi-line script otherwise cannot tell which line failed. tb = traceback.format_exc() raise Exception( json.dumps({ "exception_type": type(e).__name__, "message": str(e), "traceback": tb, }) ) # ------------------------------------------------------------------ # Documentation / introspection helpers. # # These never touch the current scene or node tree - they exist purely # to answer "what does this thing look like" questions (property names, # types, enum values, socket order, function/operator signatures) so an # LLM can get a structured answer in one call instead of guessing and # discovering the shape of things via a chain of failed execute_code # attempts. # ------------------------------------------------------------------ @staticmethod def _describe_property(prop): """Structured description of a single bpy RNA property.""" entry = { "identifier": prop.identifier, "name": prop.name, "type": prop.type, # FLOAT, INT, BOOLEAN, STRING, ENUM, POINTER, COLLECTION "description": prop.description, } for attr in ("is_required", "is_readonly", "is_argument_optional", "array_length"): value = getattr(prop, attr, None) if value is not None: entry[attr] = value if prop.type == 'ENUM': try: entry["enum_items"] = [item.identifier for item in prop.enum_items] except Exception: pass try: entry["default"] = prop.default except Exception: pass elif prop.type in ('FLOAT', 'INT'): try: entry["default"] = ( list(prop.default_array) if getattr(prop, "array_length", 0) else prop.default ) except Exception: pass for attr in ("hard_min", "hard_max", "soft_min", "soft_max", "subtype", "unit", "step"): value = getattr(prop, attr, None) if value is not None: entry[attr] = value elif prop.type == 'BOOLEAN': try: entry["default"] = prop.default except Exception: pass elif prop.type == 'STRING': try: entry["default"] = prop.default except Exception: pass max_length = getattr(prop, "max_length", None) if max_length: entry["max_length"] = max_length elif prop.type == 'POINTER': fixed_type = getattr(prop, "fixed_type", None) if fixed_type is not None: entry["pointer_type"] = fixed_type.identifier elif prop.type == 'COLLECTION': fixed_type = getattr(prop, "fixed_type", None) if fixed_type is not None: entry["collection_type"] = fixed_type.identifier return entry def describe_node_type(self, bl_idname, property_overrides=None): """Describe a node type's properties and socket schema. This is the fix for the single most common failure mode: guessing socket names/indices and enum values instead of looking them up. Since a node's sockets are only known once instantiated (and can depend on mode-like properties, e.g. Mix's `data_type`), this creates a throwaway node in a scratch node tree, optionally applies `property_overrides` first (e.g. {"data_type": "RGBA"}) so the caller can see the exact socket layout for the mode they intend to use, then reports its properties/inputs/outputs, and finally deletes the scratch tree. Nothing in the user's actual scene is touched. """ node_cls = getattr(bpy.types, bl_idname, None) if node_cls is None or not (isinstance(node_cls, type) and issubclass(node_cls, bpy.types.Node)): candidates = [ name for name in dir(bpy.types) if "Node" in name and bl_idname.lower() in name.lower() ] return { "error": f"Unknown node type: {bl_idname}", "did_you_mean": sorted(candidates)[:15], } tree_type_candidates = [ "ShaderNodeTree", "GeometryNodeTree", "CompositorNodeTree", "TextureNodeTree", ] node = None tree = None used_tree_type = None attempts = [] for tree_type in tree_type_candidates: tmp_tree = None try: tmp_tree = bpy.data.node_groups.new(name="__mcp_introspect_tmp__", type=tree_type) node = tmp_tree.nodes.new(type=bl_idname) tree = tmp_tree used_tree_type = tree_type break except Exception as e: attempts.append(f"{tree_type}: {e}") if tmp_tree is not None: try: bpy.data.node_groups.remove(tmp_tree) except Exception: pass if node is None: return { "error": f"Could not instantiate node '{bl_idname}' in any node tree type", "attempts": attempts, } try: warnings = [] if property_overrides: for key, value in property_overrides.items(): try: setattr(node, key, value) except Exception as e: warnings.append(f"Could not set property '{key}' = {value!r}: {e}") base_props = set(bpy.types.Node.bl_rna.properties.keys()) properties = [ self._describe_property(prop) for prop in node.bl_rna.properties if prop.identifier not in base_props ] def describe_sockets(sockets): out = [] for index, socket in enumerate(sockets): entry = { "index": index, "identifier": socket.identifier, "name": socket.name, "type": socket.type, "is_multi_input": getattr(socket, "is_multi_input", False), "hide_value": getattr(socket, "hide_value", False), "is_linked": socket.is_linked, } if hasattr(socket, "default_value"): try: default_value = socket.default_value if hasattr(default_value, "__len__") and not isinstance(default_value, str): entry["default_value"] = list(default_value) else: entry["default_value"] = default_value except Exception: pass out.append(entry) return out result = { "bl_idname": bl_idname, "label": node.bl_label, "instantiated_in": used_tree_type, "properties": properties, "inputs": describe_sockets(node.inputs), "outputs": describe_sockets(node.outputs), "applied_property_overrides": property_overrides or {}, "note": ( "Sockets reflect the node's current property values (after any " "property_overrides applied above). Enum/mode-like properties " "(e.g. data_type, blend_type) can add, remove or reorder sockets - " "pass the mode you intend to use via property_overrides to see the " "real layout before writing code that indexes these sockets." ), } if warnings: result["warnings"] = warnings return result finally: try: bpy.data.node_groups.remove(tree) except Exception: pass def bpy_api_lookup(self, query): """Structured RNA reference lookup: types, properties, functions, operators. Accepts things like: - "ShaderNodeTexSky" or "bpy.types.ShaderNodeTexSky" -> full type schema - "ShaderNodeTexSky.sky_type" -> one property, with enum items - "Object.ray_cast" -> one method's parameters/returns - "bpy.ops.mesh.primitive_cube_add" -> operator parameters This replaces scraping `help()` text: every answer is structured JSON with real type names, enum identifiers, and required/optional flags, not something that has to be re-parsed out of a text blob. """ query = (query or "").strip() if not query: return {"error": "Empty query"} q = query[4:] if query.startswith("bpy.") else query # bpy.ops.. if q.startswith("ops."): op_parts = q[len("ops."):].split(".") op_parts = [p.split("(")[0] for p in op_parts if p] if len(op_parts) < 2: return {"error": f"Incomplete operator path: bpy.{q}. Expected bpy.ops.."} category, op_name = op_parts[0], op_parts[1] op_group = getattr(bpy.ops, category, None) op = getattr(op_group, op_name, None) if op_group is not None else None if op is None: return {"error": f"Unknown operator: bpy.ops.{category}.{op_name}"} try: rna = op.get_rna_type() except Exception as e: return {"error": f"Could not introspect operator bpy.ops.{category}.{op_name}: {e}"} parameters = [ self._describe_property(prop) for prop in rna.properties if prop.identifier != "rna_type" ] return { "kind": "operator", "idname": f"bpy.ops.{category}.{op_name}", "label": rna.name, "description": rna.description, "parameters": parameters, } parts = [p for p in q.split(".") if p and p != "types"] if not parts: return {"error": "Empty query"} type_name = parts[0] node_cls = getattr(bpy.types, type_name, None) if node_cls is None: matches = sorted( name for name in dir(bpy.types) if type_name.lower() in name.lower() ) return { "error": f"Unknown type: {type_name}", "did_you_mean": matches[:15], } if len(parts) == 1: properties = [ self._describe_property(prop) for prop in node_cls.bl_rna.properties if prop.identifier != "rna_type" ] functions = [] for func in node_cls.bl_rna.functions: functions.append({ "identifier": func.identifier, "description": func.description, "parameters": [ self._describe_property(p) for p in func.parameters if not p.is_output ], "returns": [ self._describe_property(p) for p in func.parameters if p.is_output ], }) return { "kind": "type", "bl_idname": type_name, "description": node_cls.bl_rna.description, "properties": properties, "functions": functions, } # Type.member - could be a property or a function/method member_name = parts[1] prop = node_cls.bl_rna.properties.get(member_name) if prop is not None: entry = self._describe_property(prop) entry["kind"] = "property" entry["owner_type"] = type_name return entry func = node_cls.bl_rna.functions.get(member_name) if func is not None: return { "kind": "function", "owner_type": type_name, "identifier": func.identifier, "description": func.description, "parameters": [self._describe_property(p) for p in func.parameters if not p.is_output], "returns": [self._describe_property(p) for p in func.parameters if p.is_output], } available = sorted( list(node_cls.bl_rna.properties.keys()) + list(node_cls.bl_rna.functions.keys()) ) return { "error": f"'{type_name}' has no property or function named '{member_name}'", "did_you_mean": [name for name in available if member_name.lower() in name.lower()][:15], } def export_scene(self, filepath, format="glb", object_names=None, selection_only=False, apply_modifiers=True): """Export the whole scene, the current selection, or the named objects to a GLB or FBX file. Named objects are exported together with their children. GLB carries PBR materials, emission, skins, shape keys and animation; FBX is the fallback for tools that need Unity's built-in importer. apply_modifiers=False keeps rigs and shape keys intact. The file is written where the caller asked, so other applications (game engines, viewers) can pick it up without going through execute_code. """ if not filepath: return {"error": "filepath is required"} fmt = (format or "glb").lower() if fmt not in ("glb", "fbx"): return {"error": f"format must be glb or fbx, got '{format}'"} names = [n for n in (object_names or []) if n] use_selection = False exported = [] if names: missing = [n for n in names if bpy.data.objects.get(n) is None] if missing: return {"error": "Objects not found in Blender: " + ", ".join(missing)} bpy.ops.object.select_all(action='DESELECT') for n in names: obj = bpy.data.objects[n] for o in [obj, *obj.children_recursive]: o.select_set(True) if o.name not in exported: exported.append(o.name) bpy.context.view_layer.objects.active = bpy.data.objects[names[0]] use_selection = True elif selection_only: if not bpy.context.selected_objects: return {"error": "Nothing is selected in Blender and no object_names were given"} exported = [o.name for o in bpy.context.selected_objects] use_selection = True else: exported = [o.name for o in bpy.context.scene.objects] try: if bpy.context.object and getattr(bpy.context.object, "mode", 'OBJECT') != 'OBJECT': bpy.ops.object.mode_set(mode='OBJECT') except Exception: pass directory = os.path.dirname(filepath) if directory: os.makedirs(directory, exist_ok=True) if fmt == "glb": bpy.ops.export_scene.gltf( filepath=filepath, export_format='GLB', use_selection=use_selection, use_active_scene=True, export_apply=apply_modifiers, export_animations=True, export_skins=True, export_morph=True, export_yup=True) else: bpy.ops.export_scene.fbx( filepath=filepath, use_selection=use_selection, apply_unit_scale=True, bake_space_transform=apply_modifiers, use_mesh_modifiers=apply_modifiers, path_mode='COPY', embed_textures=True) return { "path": filepath, "bytes": os.path.getsize(filepath), "selection_only": use_selection, "exported": exported, } def get_polyhaven_categories(self, asset_type): """Get the category taxonomy and attribute schema for an asset type.""" try: if asset_type not in ["hdris", "textures", "models", "all"]: return {"error": f"Invalid asset type: {asset_type}. Must be one of: hdris, textures, models, all"} if asset_type == "all": # Three full trees at once is 30KB of paths, so this one is cut # to the top two levels. Filtering is inclusive, so those still # select everything beneath them. return { "taxonomy": [ _polyhaven_taxonomy(one, depth=POLYHAVEN_TAXONOMY_DEPTH_ALL) for one in ("hdris", "textures", "models") ], "truncated": True, } return {"taxonomy": [_polyhaven_taxonomy(asset_type)], "truncated": False} except Exception as e: return {"error": str(e)} def search_polyhaven_assets(self, asset_type=None, category=None, attributes=None, query=None, limit=None, min_size_m=None): """Search for assets from Polyhaven with optional filtering""" try: params = {} if asset_type and asset_type != "all": if asset_type not in ["hdris", "textures", "models"]: return {"error": f"Invalid asset type: {asset_type}. Must be one of: hdris, textures, models, all"} params["type"] = asset_type # `category`, not `categories`. The two are different filters over # different vocabularies: `categories` is the legacy flat tag list # ("outdoor", "man made", "floor"), while `category` takes the # single-path taxonomy that get_polyhaven_categories now returns # ("Metal/Sheet & Corrugated") and matches it inclusively, so a # parent selects everything beneath it. Sending a path to the legacy # parameter is answered with 200 and an empty object rather than an # error, so every filtered search came back silently empty. if category: params["category"] = category for key, value in (attributes or {}).items(): if value is None or value == "": continue if isinstance(value, bool): value = "true" if value else "false" elif isinstance(value, (list, tuple)): # Comma-separated values are OR'd together by the API. value = ",".join(str(v) for v in value) params[str(key)] = str(value) try: limit = int(limit) if limit else POLYHAVEN_SEARCH_LIMIT except (TypeError, ValueError): limit = POLYHAVEN_SEARCH_LIMIT limit = max(1, min(limit, POLYHAVEN_SEARCH_MAX_LIMIT)) try: assets = _polyhaven_api_get("assets", params=params, cache=True) except PolyHavenAPIError as e: if e.status == 400: # The category and attribute filters answer an unrecognised # value with 400 precisely so it is not a silent empty page. return {"error": "Poly Haven did not recognise that category or attribute " "filter. Call get_polyhaven_categories for the values each " "asset type accepts."} raise # Trimmed and lower-cased so equivalent queries share a cache entry, # both here and at Poly Haven's edge. query = (query or "").strip().lower() note = None # Filtered here rather than at the API, which publishes a real-world # size for every texture but takes no filter on it. Free: the records # are already in hand. Anything that publishes no size cannot satisfy # a floor on it and drops out - HDRIs have none. if min_size_m: try: floor_mm = float(min_size_m) * 1000 except (TypeError, ValueError): return {"error": f"min_size_m must be a number, got {min_size_m!r}"} before = len(assets) assets = { slug: record for slug, record in assets.items() if max(record.get("dimensions") or [0]) >= floor_mm } if before and not assets: # An empty page reads as "Poly Haven does not have this", # which is a different and much worse statement than "the # size floor is above everything that matched". note = (f"Nothing matching the other filters is {floor_mm / 1000:g}m or " "larger. Most textures are 1-4m, and HDRIs have no real-world " "size at all. Lower min_size_m or leave it out.") if query: try: ranked = _polyhaven_search(query, asset_type) except PolyHavenAPIError as e: if e.status == 429: wait = f" Retry in {e.retry_after}s." if e.retry_after else "" return {"error": f"Poly Haven is rate limiting searches from this " f"address.{wait}"} if e.status != 503: raise # The API documents a 503 as "the query could not be # embedded, fall back to your own keyword matching". ranked = _polyhaven_keyword_match(query, assets) note = ("Poly Haven's semantic search was unavailable, so these are plain " "keyword matches and the ranking is weaker than usual.") # /search knows nothing about the category and attribute filters, # so its ranking is intersected with the filtered list here. That # is why the whole ranked list is asked for rather than the first # `limit` of it: filtering a page that the server already cut can # only shrink it, and the matches would be the ones further down. ordered = [slug for slug in ranked if slug in assets] else: # Rank before truncating. The previous order was whatever the API # happened to return, which is sorted by slug - and because models # are the only assets with capitalised slugs, the first 20 of an # unfiltered list were 20 models. asset_type="all" could not return # a single HDRI or texture, and the library's most downloaded assets # were unreachable by any call. ordered = sorted( assets, key=lambda slug: assets[slug].get("download_count", 0), reverse=True) selected = ordered[:limit] return { "assets": [_polyhaven_summarize_asset(slug, assets[slug]) for slug in selected], # Everything matching every filter, so the count and the page it # heads describe the same population. "total_count": len(ordered), "returned_count": len(selected), "query": query or None, "note": note, } except Exception as e: return {"error": str(e)} def get_polyhaven_asset_preview(self, asset_id): """Fetch an asset's thumbnail, so it can be looked at before downloading. A thumbnail is a few hundred kilobytes against a 4k texture's 24MB, so checking one first is cheaper for everybody than importing the wrong rock. """ try: if not _polyhaven_valid_slug(asset_id): return {"error": f"Invalid asset id: {asset_id!r}. Poly Haven slugs are " "letters, digits, underscores and hyphens."} record = _polyhaven_asset_record(asset_id) thumbnail_url = record.get("thumbnail_url") if not thumbnail_url: return {"error": f"No thumbnail is published for '{asset_id}'"} response = requests.get( _polyhaven_preview_url(thumbnail_url), headers=POLYHAVEN_HEADERS, timeout=POLYHAVEN_API_TIMEOUT, ) if response.status_code >= 400: return {"error": f"Failed to fetch the thumbnail: HTTP {response.status_code}"} content_type = getattr(response, "headers", {}).get("Content-Type", "") image_format = "png" if "png" in content_type or ".png" in thumbnail_url else "jpeg" authors = record.get("authors") or {} return { "success": True, "image_data": base64.b64encode(response.content).decode("ascii"), "format": image_format, "asset_id": asset_id, "name": record.get("name") or asset_id, "authors": sorted(authors) if isinstance(authors, dict) else authors, "url": _polyhaven_asset_url(asset_id), } except Exception as e: traceback.print_exc() return {"error": f"Failed to get asset preview: {str(e)}"} def download_polyhaven_asset(self, asset_id, asset_type, resolution="1k", file_format=None): try: if asset_type not in POLYHAVEN_SUPPORTED_FORMATS: return {"error": f"Unsupported asset type: {asset_type}. Must be one of: hdris, textures, models"} if not _polyhaven_valid_slug(asset_id): return {"error": f"Invalid asset id: {asset_id!r}. Poly Haven slugs are " "letters, digits, underscores and hyphens."} supported = POLYHAVEN_SUPPORTED_FORMATS[asset_type] file_format = (file_format or POLYHAVEN_DEFAULT_FORMATS[asset_type]).lower() if file_format not in supported: # Rejected before any transfer. `usd` is listed for every model # and used to be downloaded in full before reaching the # "unsupported format" branch at the end of the import. return { "error": f"Unsupported {asset_type} format: {file_format}. " f"Supported formats: {', '.join(supported)}" } try: files_data = _polyhaven_api_get(f"files/{quote(asset_id, safe='')}") except Exception as e: return {"error": f"Failed to get asset files for '{asset_id}': {str(e)}"} if asset_type == "hdris": return self._polyhaven_import_hdri(asset_id, files_data, resolution, file_format) if asset_type == "textures": return self._polyhaven_import_texture(asset_id, files_data, resolution, file_format) return self._polyhaven_import_model(asset_id, files_data, resolution, file_format) except Exception as e: traceback.print_exc() return {"error": f"Failed to download asset: {str(e)}"} def _polyhaven_import_hdri(self, asset_id, files_data, resolution, file_format): """Download an HDRI and set it up as the scene's world.""" file_info = files_data.get("hdri", {}).get(resolution, {}).get(file_format) if not file_info: return { "error": f"HDRI '{asset_id}' has no {resolution} {file_format} - " f"{_polyhaven_available(files_data, 'hdris')}" } dest_dir = tempfile.mkdtemp(prefix="blender_mcp_polyhaven_") dest_path = os.path.join(dest_dir, f"{asset_id}_{resolution}.{file_format}") try: _polyhaven_download(file_info, dest_path) except Exception as e: shutil.rmtree(dest_dir, ignore_errors=True) return {"error": f"Failed to download HDRI: {str(e)}"} try: # A new world every time, rather than clearing the nodes of whatever # world is already there. The old code took bpy.data.worlds[0] - the # alphabetically first world datablock, very often somebody else's - # wiped its nodes and made it active, destroying hand-built setups # with no undo step to recover them. Using the scene's own world # instead would still have wiped it. This leaves the previous world # intact and simply unused; without a fake user Blender clears it up # on save if nothing else references it, and it is recoverable from # the outliner's orphan data until then. world = bpy.data.worlds.new(f"PolyHaven {asset_id}") bpy.context.scene.world = world world.use_nodes = True node_tree = world.node_tree node_tree.nodes.clear() tex_coord = node_tree.nodes.new(type='ShaderNodeTexCoord') tex_coord.location = (-800, 0) mapping = node_tree.nodes.new(type='ShaderNodeMapping') mapping.location = (-600, 0) env_tex = node_tree.nodes.new(type='ShaderNodeTexEnvironment') env_tex.location = (-400, 0) env_tex.image = bpy.data.images.load(dest_path, check_existing=True) env_tex.image.name = f"{asset_id}_{resolution}" # Colorspace is deliberately left as Blender's loader set it. It # already tags .hdr/.exr as scene-linear, and forcing "Non-Color" # here would mark radiance data as raw - identical under the stock # OCIO config, a colour shift under any config whose working space # is not Linear Rec.709. # Pack before anything can remove the file underneath it. Without # this the world points at a path in the OS temp directory for the # life of the .blend: it renders now, and is a missing image the # next time the file is opened here - or the first time it is opened # anywhere else. env_tex.image.pack() background = node_tree.nodes.new(type='ShaderNodeBackground') background.location = (-200, 0) output = node_tree.nodes.new(type='ShaderNodeOutputWorld') output.location = (0, 0) node_tree.links.new(tex_coord.outputs['Generated'], mapping.inputs['Vector']) node_tree.links.new(mapping.outputs['Vector'], env_tex.inputs['Vector']) node_tree.links.new(env_tex.outputs['Color'], background.inputs['Color']) node_tree.links.new(background.outputs['Background'], output.inputs['Surface']) bpy.context.scene.world = world authors = _polyhaven_authors(asset_id) _polyhaven_tag([world, env_tex.image], asset_id, resolution, authors) return { "success": True, "message": f"HDRI {asset_id} imported successfully", "image_name": env_tex.image.name, "world": world.name, "authors": authors, "url": _polyhaven_asset_url(asset_id), } except Exception as e: traceback.print_exc() return {"error": f"Failed to set up HDRI in Blender: {str(e)}"} finally: # The image is packed, so nothing needs the file any more. shutil.rmtree(dest_dir, ignore_errors=True) def _polyhaven_build_material(self, asset_id, maps): """Build a Principled material from {map_key: (role, image)}. Shared by download_polyhaven_asset and set_texture so there is exactly one place that decides which map drives which input - set_texture used to build its own tree in two passes over the same maps, silently replacing every link it had just made and leaving the first pass's Normal Map and Displacement nodes orphaned in the tree. """ mat = bpy.data.materials.new(name=asset_id) mat.use_nodes = True nodes = mat.node_tree.nodes links = mat.node_tree.links nodes.clear() output = nodes.new(type='ShaderNodeOutputMaterial') output.location = (600, 0) principled = nodes.new(type='ShaderNodeBsdfPrincipled') principled.location = (300, 0) links.new(principled.outputs[0], output.inputs['Surface']) tex_coord = nodes.new(type='ShaderNodeTexCoord') tex_coord.location = (-1000, 0) mapping = nodes.new(type='ShaderNodeMapping') mapping.location = (-800, 0) # POINT is Blender's default and the mode Poly Haven authors its own # materials in - the Mapping node published inside every texture .blend # is left at POINT, and the add-on's real-world-scale operator solves for # a Scale that grows as the surface grows. TEXTURE is its exact inverse # ("transform a texture by inverse mapping the texture coordinate"), so # the natural arithmetic - Scale = surface size / texture size - came out # upside down, and a 2m texture asked to repeat twice repeated half a # time instead. At Scale 1.0 the two modes are identical, so this moves # nothing that was not already inverted. mapping.vector_type = 'POINT' links.new(tex_coord.outputs['UV'], mapping.inputs['Vector']) y_pos = 300 wired = [] for map_key, (role, image) in maps.items(): tex_node = nodes.new(type='ShaderNodeTexImage') tex_node.location = (-500, y_pos) tex_node.image = image _polyhaven_set_colorspace(image, is_color_data=role in POLYHAVEN_COLOR_ROLES) links.new(mapping.outputs['Vector'], tex_node.inputs['Vector']) y_pos -= 300 if role == "base_color": links.new(tex_node.outputs['Color'], principled.inputs['Base Color']) elif role == "roughness": links.new(tex_node.outputs['Color'], principled.inputs['Roughness']) elif role == "metallic": links.new(tex_node.outputs['Color'], principled.inputs['Metallic']) elif role == "normal": normal_map = nodes.new(type='ShaderNodeNormalMap') normal_map.location = (-200, tex_node.location[1]) links.new(tex_node.outputs['Color'], normal_map.inputs['Color']) links.new(normal_map.outputs['Normal'], principled.inputs['Normal']) elif role == "displacement": disp_node = nodes.new(type='ShaderNodeDisplacement') disp_node.location = (300, tex_node.location[1]) # Poly Haven's displacement maps are centred on 0.5, and the # output is only used at all once the material is told to # displace - otherwise the node sits there connected and inert. disp_node.inputs['Midlevel'].default_value = 0.5 disp_node.inputs['Scale'].default_value = 0.1 links.new(tex_node.outputs['Color'], disp_node.inputs['Height']) links.new(disp_node.outputs['Displacement'], output.inputs['Displacement']) # Moved off material.cycles in Blender 4.1; try both so the # node is not left connected but inert on older versions. if hasattr(mat, "displacement_method"): mat.displacement_method = 'BOTH' else: with suppress(Exception): mat.cycles.displacement_method = 'BOTH' else: continue wired.append(map_key) return mat, wired def _polyhaven_import_texture(self, asset_id, files_data, resolution, file_format): """Download a texture's maps and build a material from them.""" wanted = _polyhaven_select_texture_maps(files_data, resolution, file_format) if not wanted: return { "error": f"Texture '{asset_id}' has no maps at {resolution} {file_format} - " f"{_polyhaven_available(files_data, 'textures')}" } dest_dir = tempfile.mkdtemp(prefix="blender_mcp_polyhaven_") maps = {} try: for map_key, role in wanted.items(): file_info = files_data[map_key][resolution][file_format] dest_path = os.path.join( dest_dir, f"{asset_id}_{map_key}_{resolution}.{file_format}" ) _polyhaven_download(file_info, dest_path) image = bpy.data.images.load(dest_path, check_existing=True) image.name = f"{asset_id}_{map_key}" _polyhaven_set_colorspace(image, is_color_data=role in POLYHAVEN_COLOR_ROLES) image.pack() maps[map_key] = (role, image) except Exception as e: traceback.print_exc() return {"error": f"Failed to download texture maps: {str(e)}"} finally: # Every image is packed, so nothing needs the files any more. shutil.rmtree(dest_dir, ignore_errors=True) try: mat, wired = self._polyhaven_build_material(asset_id, maps) # Deliberately no fake user. A material nothing has been applied to # is not being used, and Blender discarding it on save is the # correct outcome rather than a leak to guard against - the same # reasoning as the world this no longer keeps alive either. Call # set_texture to give it a real user. authors = _polyhaven_authors(asset_id) dimensions = _polyhaven_dimensions_mm(asset_id) _polyhaven_tag( [mat] + [image for _role, image in maps.values()], asset_id, resolution=resolution, authors=authors, dimensions=dimensions, ) for map_key, (role, image) in maps.items(): with suppress(Exception): image["polyhaven_map"] = map_key image["polyhaven_role"] = role mapping = _polyhaven_mapping_node(mat.node_tree) return { "success": True, "message": f"Texture {asset_id} imported as material", "material": mat.name, "maps": wired, "authors": authors, "url": _polyhaven_asset_url(asset_id), # What the material has to be told before it is applied to # anything, reported next to the material itself rather than # left in a search result several steps back. "scale_mm": dimensions, "mapping_node": None if mapping is None else mapping.name, } except Exception as e: traceback.print_exc() return {"error": f"Failed to build material: {str(e)}"} def _polyhaven_fetch_model_files(self, files_data, resolution, file_format, dest_dir): """Download a model's main file and its sidecar textures into dest_dir.""" file_info = files_data.get(file_format, {}).get(resolution, {}).get(file_format) if not file_info: return None main_file_path = os.path.join(dest_dir, os.path.basename(file_info["url"].split("?")[0])) _polyhaven_download(file_info, main_file_path) for include_path, include_info in (file_info.get("include") or {}).items(): # Validate include_path - the API response controls these # dict keys; a malicious or MITM'd response could request an # absolute path or one containing ".." to escape dest_dir # and write arbitrary files (e.g. ~/.bashrc, authorized_keys). # Mirrors the zip-slip check in download_sketchfab_model. target_path = os.path.join(dest_dir, os.path.normpath(include_path)) abs_dest_dir = os.path.abspath(dest_dir) abs_target_path = os.path.abspath(target_path) if (os.path.isabs(include_path) or ".." in include_path or not abs_target_path.startswith(abs_dest_dir + os.sep)): print(f"Skipping include with unsafe path: {include_path}") continue os.makedirs(os.path.dirname(target_path), exist_ok=True) _polyhaven_download(include_info, target_path) return main_file_path def _polyhaven_append_blend(self, blend_path, asset_id): """Append the asset's own collection out of a Poly Haven model .blend. Every published model holds a collection named exactly the slug - it is an error in Poly Haven's own asset checker if it does not - and models with levels of detail carry them as `_LOD0`, `_LOD1` and so on beneath it. Appending `data_from.objects` wholesale, as this used to, linked every LOD on top of each other plus whatever else the file happened to hold, which for some assets is a second model. """ with bpy.data.libraries.load(blend_path, link=False) as (data_from, data_to): available = list(data_from.collections) # LOD0 is the full-detail version. Taking it directly leaves the # coarser ones in the file rather than in the scene. wanted = next( (name for name in (f"{asset_id}_LOD0", asset_id) if name in available), None) if wanted: data_to.collections = [wanted] else: # Nothing to key off. Fall back to the old behaviour rather than # importing nothing at all. data_to.objects = data_from.objects linked = [] for collection in data_to.collections: if collection is not None: bpy.context.scene.collection.children.link(collection) linked.append(collection) if not linked: for obj in data_to.objects: if obj is not None: bpy.context.collection.objects.link(obj) return linked def _polyhaven_import_model(self, asset_id, files_data, resolution, file_format): """Download a model and its textures, then import it.""" if not files_data.get(file_format, {}).get(resolution, {}).get(file_format): return { "error": f"Model {asset_id!r} has no {resolution} {file_format} - " f"{_polyhaven_available(files_data, 'models')}" } dest_dir = tempfile.mkdtemp(prefix="blender_mcp_polyhaven_") fallback_note = "" collections = [] try: main_file_path = self._polyhaven_fetch_model_files( files_data, resolution, file_format, dest_dir) except Exception as e: traceback.print_exc() shutil.rmtree(dest_dir, ignore_errors=True) return {"error": f"Failed to download model: {str(e)}"} # By name: bpy hands out a fresh Python wrapper per access, so holding on # to the datablocks themselves invites identity bugs. before = {obj.name for obj in bpy.data.objects} try: if file_format == "blend": written_by = _polyhaven_blend_version(main_file_path) if written_by and written_by > bpy.app.version[:2]: raise RuntimeError("written by Blender %d.%d" % written_by) collections = self._polyhaven_append_blend(main_file_path, asset_id) else: bpy.ops.import_scene.gltf(filepath=main_file_path) except Exception as blend_error: if file_format != "blend": traceback.print_exc() shutil.rmtree(dest_dir, ignore_errors=True) return {"error": f"Failed to import model: {str(blend_error)}"} # A .blend written by a newer Blender than this one cannot be opened # at all, and Poly Haven's oldest models were saved in 2.93 while its # newest were saved in 5.0. glTF is a poorer record of the material, # but it is the difference between a worse model and no model. print(f"Poly Haven: .blend import failed ({blend_error}), falling back to glTF") shutil.rmtree(dest_dir, ignore_errors=True) dest_dir = tempfile.mkdtemp(prefix="blender_mcp_polyhaven_") fallback_note = ( f" Imported from glTF rather than .blend, because the .blend was {blend_error}" f" and this is Blender {bpy.app.version_string.split()[0]}. Its materials are a" " conversion rather than the ones the artist built." ) try: before = {obj.name for obj in bpy.data.objects} fallback_path = self._polyhaven_fetch_model_files( files_data, resolution, POLYHAVEN_MODEL_FALLBACK_FORMAT, dest_dir) if not fallback_path: raise RuntimeError(f"no {resolution} glTF is published for it") bpy.ops.import_scene.gltf(filepath=fallback_path) except Exception as e: traceback.print_exc() shutil.rmtree(dest_dir, ignore_errors=True) return { "error": f"Model {asset_id!r} is {blend_error}, which this Blender cannot " f"open, and the glTF fallback failed too: {str(e)}" } try: imported = [obj for obj in bpy.data.objects if obj.name not in before] imported_objects = [obj.name for obj in imported] if not imported_objects: return {"error": f"Imported {asset_id} but nothing arrived in the scene. " "The .blend may not hold the collection this expects."} # Appended and glTF-imported images still reference the files in the # temporary directory this deletes on the way out. A .glb carries its # textures inside it, but a .gltf with sidecar files does not, and an # appended .blend never does. materials = [] for obj in imported: for slot in getattr(obj, "material_slots", []): if slot.material is None: continue if slot.material not in materials: materials.append(slot.material) if not slot.material.use_nodes: continue for node in slot.material.node_tree.nodes: if node.type == 'TEX_IMAGE' and node.image and not node.image.packed_file: with suppress(Exception): node.image.pack() authors = _polyhaven_authors(asset_id) _polyhaven_tag(imported + collections + materials, asset_id, resolution, authors) return { "success": True, "message": f"Model {asset_id} imported successfully.{fallback_note}", "imported_objects": imported_objects, "authors": authors, "url": _polyhaven_asset_url(asset_id), } except Exception as e: traceback.print_exc() return {"error": f"Failed to import model: {str(e)}"} finally: shutil.rmtree(dest_dir, ignore_errors=True) def _polyhaven_material_info(self, mat): """Summarise a material's node tree for the caller.""" texture_nodes = [] for node in mat.node_tree.nodes: if node.type != 'TEX_IMAGE' or node.image is None: continue connections = [] for link in mat.node_tree.links: if link.from_node == node: connections.append( f"{link.from_socket.name} -> {link.to_node.name}.{link.to_socket.name}" ) texture_nodes.append({ "name": node.name, "image": node.image.name, "colorspace": node.image.colorspace_settings.name, "connections": connections, }) # Every image node's Vector input comes from here, so this is the one # node that decides the tiling - and it could not appear in this report, # which described TEX_IMAGE nodes and nothing else. mapping = _polyhaven_mapping_node(mat.node_tree) return { "has_nodes": mat.use_nodes, "node_count": len(mat.node_tree.nodes), "texture_nodes": texture_nodes, "mapping_node": None if mapping is None else { "name": mapping.name, "vector_type": mapping.vector_type, "scale": list(mapping.inputs['Scale'].default_value), }, } def set_texture(self, object_name, texture_id): """Apply a previously downloaded Polyhaven texture to an object by creating a new material""" try: obj = bpy.data.objects.get(object_name) if not obj: return {"error": f"Object not found: {object_name}"} if not hasattr(obj, 'data') or not hasattr(obj.data, 'materials'): return {"error": f"Object {object_name} cannot accept materials"} if not _polyhaven_valid_slug(texture_id): return {"error": f"Invalid texture id: {texture_id!r}"} # Identified by the custom property stamped at download time rather # than by parsing the image's name. The old parser took the last # underscore-separated token, which turned "nor_gl" into "gl" and # left the two functions disagreeing about what a map was called. maps = {} for img in bpy.data.images: if img.get("polyhaven_id") != texture_id: continue map_key = img.get("polyhaven_map") # Role first: assets whose albedo is not called "Diffuse" are # not in the table, but were resolved at download time. role = img.get("polyhaven_role") or POLYHAVEN_TEXTURE_MAPS.get(map_key) if not role: continue if not img.packed_file: img.pack() # An asset downloaded at more than one resolution leaves several # images per map, all carrying the same id. Take the largest # rather than whichever happened to come last. existing = maps.get(map_key) if existing and _polyhaven_resolution_rank( existing[1].get("polyhaven_resolution")) >= _polyhaven_resolution_rank( img.get("polyhaven_resolution")): continue maps[map_key] = (role, img) if not maps: return { "error": f"No texture images found for: {texture_id}. " "Download it first with download_polyhaven_asset." } new_mat_name = f"{texture_id}_material_{object_name}" existing_mat = bpy.data.materials.get(new_mat_name) if existing_mat: bpy.data.materials.remove(existing_mat) new_mat, wired = self._polyhaven_build_material(texture_id, maps) new_mat.name = new_mat_name authors = _polyhaven_authors(texture_id) _polyhaven_tag([new_mat], texture_id, authors=authors, dimensions=_polyhaven_dimensions_mm(texture_id)) # Note: this replaces every material slot on the object. replaced = len(obj.data.materials) while len(obj.data.materials) > 0: obj.data.materials.pop(index=0) obj.data.materials.append(new_mat) bpy.context.view_layer.objects.active = obj obj.select_set(True) bpy.context.view_layer.update() message = f"Created new material and applied texture {texture_id} to {object_name}" if replaced: message += f" (replaced {replaced} existing material slot{'s' if replaced != 1 else ''})" return { "success": True, "message": message, "material": new_mat.name, "maps": wired, "material_info": self._polyhaven_material_info(new_mat), "authors": authors, "url": _polyhaven_asset_url(texture_id), } except Exception as e: print(f"Error in set_texture: {str(e)}") traceback.print_exc() return {"error": f"Failed to apply texture: {str(e)}"} def get_telemetry_consent(self): """Get the current telemetry consent status. Fails closed: if preferences cannot be read we report no consent. Not being able to read the preference means we do not know the user's answer, which is not the same as them having said yes. """ try: # Get addon preferences - use the module name addon_prefs = bpy.context.preferences.addons.get(__name__) if addon_prefs: consent = bool(addon_prefs.preferences.telemetry_consent) else: consent = False except (AttributeError, KeyError): consent = False return {"consent": consent} def set_telemetry_consent(self, consent=False): """Write the telemetry consent preference. Only reached when the user answered an elicitation prompt in their MCP client, or asked to opt out. Assigning the property in code skips the BoolProperty update= callback, so the manual-edit handlers are re-synced explicitly. """ try: addon_prefs = bpy.context.preferences.addons.get(__name__) if not addon_prefs: return {"error": "Could not read addon preferences"} addon_prefs.preferences.telemetry_consent = bool(consent) except (AttributeError, KeyError) as e: return {"error": f"Could not set telemetry consent: {e}"} try: sync_edit_capture_handlers() except Exception as e: print(f"BlenderMCP: could not sync manual edit handlers: {e}") return {"consent": bool(consent)} def get_polyhaven_status(self): """Get the current status of PolyHaven integration""" enabled = bpy.context.scene.blendermcp_use_polyhaven if enabled: return {"enabled": True, "message": "PolyHaven integration is enabled and ready to use."} else: return { "enabled": False, "message": """PolyHaven integration is currently disabled. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Check the 'Use assets from Poly Haven' checkbox 3. Restart the connection to Claude""" } #region Hyper3D def get_hyper3d_status(self): """Get the current status of Hyper3D Rodin integration""" if premium_active(): return premium_integration_status("hyper3d", bpy.context.scene.blendermcp_use_hyper3d) enabled = bpy.context.scene.blendermcp_use_hyper3d hyper3d_api_key = self._get_hyper3d_api_key() if enabled: if not hyper3d_api_key: return { "enabled": False, "message": """Hyper3D Rodin integration is currently enabled, but API key is not given. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Keep the 'Use Hyper3D Rodin 3D model generation' checkbox checked 3. Choose the right plaform and fill in the API Key 4. Restart the connection to Claude""" } mode = bpy.context.scene.blendermcp_hyper3d_mode message = f"Hyper3D Rodin integration is enabled and ready to use. Mode: {mode}. " + \ f"Key type: {'private' if hyper3d_api_key != RODIN_FREE_TRIAL_KEY else 'free_trial'}" return { "enabled": True, "message": message } else: return { "enabled": False, "message": """Hyper3D Rodin integration is currently disabled. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Check the 'Use Hyper3D Rodin 3D model generation' checkbox 3. Restart the connection to Claude""" } def create_rodin_job(self, *args, **kwargs): if premium_active(): return premium_create_rodin_job(*args, **kwargs) match bpy.context.scene.blendermcp_hyper3d_mode: case "MAIN_SITE": return self.create_rodin_job_main_site(*args, **kwargs) case "FAL_AI": return self.create_rodin_job_fal_ai(*args, **kwargs) case _: return f"Error: Unknown Hyper3D Rodin mode!" def create_rodin_job_main_site( self, text_prompt: str=None, images: list[tuple[str, str]]=None, bbox_condition=None ): try: api_key = self._get_hyper3d_api_key() if not api_key: return {"error": "Hyper3D API key is not given"} if images is None: images = [] """Call Rodin API, get the job uuid and subscription key""" files = [ *[("images", (f"{i:04d}{img_suffix}", base64.b64decode(img) if isinstance(img, str) else img)) for i, (img_suffix, img) in enumerate(images)], ("tier", (None, "Gen-2.5-Medium")), ("mesh_mode", (None, "Raw")), ("texture_mode", (None, "high")), ] if text_prompt: files.append(("prompt", (None, text_prompt))) if bbox_condition: files.append(("bbox_condition", (None, json.dumps(bbox_condition)))) response = requests.post( "https://hyperhuman.deemos.com/api/v2/rodin", headers={ "Authorization": f"Bearer {api_key}", }, files=files, timeout=60, ) data = response.json() return data except Exception as e: return {"error": str(e)} def create_rodin_job_fal_ai( self, text_prompt: str=None, images: list[tuple[str, str]]=None, bbox_condition=None ): try: api_key = self._get_hyper3d_api_key() if not api_key: return {"error": "Hyper3D API key is not given"} req_data = { "tier": "Gen-2.5-Medium", } if images: req_data["image_urls"] = [ image if isinstance(image, str) else f"data:image/{image[0].lstrip('.').lower().replace('jpg', 'jpeg')};base64,{image[1]}" for image in images ] if text_prompt: req_data["prompt"] = text_prompt if bbox_condition: # v2.5 takes an object, not the [length, width, height] list. length, width, height = bbox_condition req_data["bbox_condition"] = {"length": length, "width": width, "height": height} response = requests.post( ("https://queue.fal.run/fal-ai/hyper3d/rodin/v2.5" if images else "https://queue.fal.run/fal-ai/hyper3d/rodin/v2.5/text-to-3d"), headers={ "Authorization": f"Key {api_key}", "Content-Type": "application/json", }, json=req_data, timeout=60, ) data = response.json() return data except Exception as e: return {"error": str(e)} def poll_rodin_job_status(self, *args, **kwargs): if premium_active(): return premium_poll_fal_job(kwargs.get("request_id") or kwargs.get("subscription_key")) match bpy.context.scene.blendermcp_hyper3d_mode: case "MAIN_SITE": return self.poll_rodin_job_status_main_site(*args, **kwargs) case "FAL_AI": return self.poll_rodin_job_status_fal_ai(*args, **kwargs) case _: return f"Error: Unknown Hyper3D Rodin mode!" def poll_rodin_job_status_main_site(self, subscription_key: str): """Call the job status API to get the job status""" api_key = self._get_hyper3d_api_key() if not api_key: return {"error": "Hyper3D API key is not given"} response = requests.post( "https://hyperhuman.deemos.com/api/v2/status", headers={ "Authorization": f"Bearer {api_key}", }, json={ "subscription_key": subscription_key, }, timeout=30, ) data = response.json() return { "status_list": [i["status"] for i in data["jobs"]] } def poll_rodin_job_status_fal_ai(self, request_id: str): """Call the job status API to get the job status""" api_key = self._get_hyper3d_api_key() if not api_key: return {"error": "Hyper3D API key is not given"} response = requests.get( f"https://queue.fal.run/fal-ai/hyper3d/requests/{request_id}/status", headers={ "Authorization": f"KEY {api_key}", }, timeout=30, ) data = response.json() return data @staticmethod def _clean_imported_glb(filepath, mesh_name=None): # Get the set of existing objects before import existing_objects = set(bpy.data.objects) # Import the GLB file bpy.ops.import_scene.gltf(filepath=filepath) # Ensure the context is updated bpy.context.view_layer.update() # Get all imported objects imported_objects = list(set(bpy.data.objects) - existing_objects) # imported_objects = [obj for obj in bpy.context.view_layer.objects if obj.select_get()] if not imported_objects: print("Error: No objects were imported.") return # Identify the mesh object mesh_obj = None if len(imported_objects) == 1 and imported_objects[0].type == 'MESH': mesh_obj = imported_objects[0] print("Single mesh imported, no cleanup needed.") else: if len(imported_objects) == 2: empty_objs = [i for i in imported_objects if i.type == "EMPTY"] if len(empty_objs) != 1: print("Error: Expected an empty node with one mesh child or a single mesh object.") return parent_obj = empty_objs.pop() if len(parent_obj.children) == 1: potential_mesh = parent_obj.children[0] if potential_mesh.type == 'MESH': print("GLB structure confirmed: Empty node with one mesh child.") # Unparent the mesh from the empty node potential_mesh.parent = None # Remove the empty node bpy.data.objects.remove(parent_obj) print("Removed empty node, keeping only the mesh.") mesh_obj = potential_mesh else: print("Error: Child is not a mesh object.") return else: print("Error: Expected an empty node with one mesh child or a single mesh object.") return else: print("Error: Expected an empty node with one mesh child or a single mesh object.") return # Rename the mesh if needed try: if mesh_obj and mesh_obj.name is not None and mesh_name: mesh_obj.name = mesh_name if mesh_obj.data.name is not None: mesh_obj.data.name = mesh_name print(f"Mesh renamed to: {mesh_name}") except Exception as e: print("Having issue with renaming, give up renaming.") return mesh_obj def import_generated_asset(self, *args, **kwargs): if premium_active(): return premium_import_job(kwargs.get("request_id") or kwargs.get("task_uuid"), kwargs.get("name")) match bpy.context.scene.blendermcp_hyper3d_mode: case "MAIN_SITE": return self.import_generated_asset_main_site(*args, **kwargs) case "FAL_AI": return self.import_generated_asset_fal_ai(*args, **kwargs) case _: return f"Error: Unknown Hyper3D Rodin mode!" def import_generated_asset_main_site(self, task_uuid: str, name: str): """Fetch the generated asset, import into blender""" api_key = self._get_hyper3d_api_key() if not api_key: return {"succeed": False, "error": "Hyper3D API key is not given"} response = requests.post( "https://hyperhuman.deemos.com/api/v2/download", headers={ "Authorization": f"Bearer {api_key}", }, json={ 'task_uuid': task_uuid }, timeout=30, ) data_ = response.json() temp_file = None for i in data_["list"]: if i["name"].endswith(".glb"): temp_file = tempfile.NamedTemporaryFile( delete=False, prefix=task_uuid, suffix=".glb", ) try: # Download the content response = requests.get(i["url"], stream=True, timeout=120) response.raise_for_status() # Raise an exception for HTTP errors # Write the content to the temporary file for chunk in response.iter_content(chunk_size=8192): temp_file.write(chunk) # Close the file temp_file.close() except Exception as e: # Clean up the file if there's an error temp_file.close() os.unlink(temp_file.name) return {"succeed": False, "error": str(e)} break else: return {"succeed": False, "error": "Generation failed. Please first make sure that all jobs of the task are done and then try again later."} try: obj = self._clean_imported_glb( filepath=temp_file.name, mesh_name=name ) result = { "name": obj.name, "type": obj.type, "location": [obj.location.x, obj.location.y, obj.location.z], "rotation": [obj.rotation_euler.x, obj.rotation_euler.y, obj.rotation_euler.z], "scale": [obj.scale.x, obj.scale.y, obj.scale.z], } if obj.type == "MESH": bounding_box = self._get_aabb(obj) result["world_bounding_box"] = bounding_box return { "succeed": True, **result } except Exception as e: return {"succeed": False, "error": str(e)} def import_generated_asset_fal_ai(self, request_id: str, name: str): """Fetch the generated asset, import into blender""" api_key = self._get_hyper3d_api_key() if not api_key: return {"succeed": False, "error": "Hyper3D API key is not given"} response = requests.get( f"https://queue.fal.run/fal-ai/hyper3d/requests/{request_id}", headers={ "Authorization": f"Key {api_key}", }, timeout=30, ) data_ = response.json() temp_file = None temp_file = tempfile.NamedTemporaryFile( delete=False, prefix=request_id, suffix=".glb", ) try: # Download the content response = requests.get(data_["model_mesh"]["url"], stream=True, timeout=120) response.raise_for_status() # Raise an exception for HTTP errors # Write the content to the temporary file for chunk in response.iter_content(chunk_size=8192): temp_file.write(chunk) # Close the file temp_file.close() except Exception as e: # Clean up the file if there's an error temp_file.close() os.unlink(temp_file.name) return {"succeed": False, "error": str(e)} try: obj = self._clean_imported_glb( filepath=temp_file.name, mesh_name=name ) result = { "name": obj.name, "type": obj.type, "location": [obj.location.x, obj.location.y, obj.location.z], "rotation": [obj.rotation_euler.x, obj.rotation_euler.y, obj.rotation_euler.z], "scale": [obj.scale.x, obj.scale.y, obj.scale.z], } if obj.type == "MESH": bounding_box = self._get_aabb(obj) result["world_bounding_box"] = bounding_box return { "succeed": True, **result } except Exception as e: return {"succeed": False, "error": str(e)} #endregion #region Sketchfab API def get_sketchfab_status(self): """Get the current status of Sketchfab integration""" enabled = bpy.context.scene.blendermcp_use_sketchfab api_key = self._get_sketchfab_api_key() # Test the API key if present if api_key and enabled: try: headers = { "Authorization": f"Token {api_key}" } response = requests.get( "https://api.sketchfab.com/v3/me", headers=headers, timeout=30 # Add timeout of 30 seconds ) if response.status_code == 200: user_data = response.json() username = user_data.get("username", "Unknown user") return { "enabled": True, "message": f"Sketchfab integration is enabled and ready to use. Logged in as: {username}" } else: return { "enabled": False, "message": f"Sketchfab API key seems invalid. Status code: {response.status_code}" } except requests.exceptions.Timeout: return { "enabled": False, "message": "Timeout connecting to Sketchfab API. Check your internet connection." } except Exception as e: return { "enabled": False, "message": f"Error testing Sketchfab API key: {str(e)}" } if enabled and api_key: return {"enabled": True, "message": "Sketchfab integration is enabled and ready to use."} elif enabled and not api_key: return { "enabled": False, "message": """Sketchfab integration is currently enabled, but API key is not given. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Keep the 'Use Sketchfab' checkbox checked 3. Enter your Sketchfab API Key 4. Restart the connection to Claude""" } else: return { "enabled": False, "message": """Sketchfab integration is currently disabled. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Check the 'Use assets from Sketchfab' checkbox 3. Enter your Sketchfab API Key 4. Restart the connection to Claude""" } def search_sketchfab_models(self, query, categories=None, count=20, downloadable=True): """Search for models on Sketchfab based on query and optional filters""" try: api_key = self._get_sketchfab_api_key() if not api_key: return {"error": "Sketchfab API key is not configured"} # Build search parameters with exact fields from Sketchfab API docs params = { "type": "models", "q": query, "count": count, "downloadable": downloadable, "archives_flavours": False } if categories: params["categories"] = categories # Make API request to Sketchfab search endpoint # The proper format according to Sketchfab API docs for API key auth headers = { "Authorization": f"Token {api_key}" } # Use the search endpoint as specified in the API documentation response = requests.get( "https://api.sketchfab.com/v3/search", headers=headers, params=params, timeout=30 # Add timeout of 30 seconds ) if response.status_code == 401: return {"error": "Authentication failed (401). Check your API key."} if response.status_code != 200: return {"error": f"API request failed with status code {response.status_code}"} response_data = response.json() # Safety check on the response structure if response_data is None: return {"error": "Received empty response from Sketchfab API"} # Handle 'results' potentially missing from response results = response_data.get("results", []) if not isinstance(results, list): return {"error": f"Unexpected response format from Sketchfab API: {response_data}"} return response_data except requests.exceptions.Timeout: return {"error": "Request timed out. Check your internet connection."} except json.JSONDecodeError as e: return {"error": f"Invalid JSON response from Sketchfab API: {str(e)}"} except Exception as e: import traceback traceback.print_exc() return {"error": str(e)} def get_sketchfab_model_preview(self, uid): """Get thumbnail preview image of a Sketchfab model by its UID""" try: import base64 api_key = self._get_sketchfab_api_key() if not api_key: return {"error": "Sketchfab API key is not configured"} headers = {"Authorization": f"Token {api_key}"} # Get model info which includes thumbnails response = requests.get( f"https://api.sketchfab.com/v3/models/{uid}", headers=headers, timeout=30 ) if response.status_code == 401: return {"error": "Authentication failed (401). Check your API key."} if response.status_code == 404: return {"error": f"Model not found: {uid}"} if response.status_code != 200: return {"error": f"Failed to get model info: {response.status_code}"} data = response.json() thumbnails = data.get("thumbnails", {}).get("images", []) if not thumbnails: return {"error": "No thumbnail available for this model"} # Find a suitable thumbnail (prefer medium size ~640px) selected_thumbnail = None for thumb in thumbnails: width = thumb.get("width", 0) if 400 <= width <= 800: selected_thumbnail = thumb break # Fallback to the first available thumbnail if not selected_thumbnail: selected_thumbnail = thumbnails[0] thumbnail_url = selected_thumbnail.get("url") if not thumbnail_url: return {"error": "Thumbnail URL not found"} # Download the thumbnail image img_response = requests.get(thumbnail_url, timeout=30) if img_response.status_code != 200: return {"error": f"Failed to download thumbnail: {img_response.status_code}"} # Encode image as base64 image_data = base64.b64encode(img_response.content).decode('ascii') # Determine format from content type or URL content_type = img_response.headers.get("Content-Type", "") if "png" in content_type or thumbnail_url.endswith(".png"): img_format = "png" else: img_format = "jpeg" # Get additional model info for context model_name = data.get("name", "Unknown") author = data.get("user", {}).get("username", "Unknown") return { "success": True, "image_data": image_data, "format": img_format, "model_name": model_name, "author": author, "uid": uid, "thumbnail_width": selected_thumbnail.get("width"), "thumbnail_height": selected_thumbnail.get("height") } except requests.exceptions.Timeout: return {"error": "Request timed out. Check your internet connection."} except Exception as e: import traceback traceback.print_exc() return {"error": f"Failed to get model preview: {str(e)}"} def download_sketchfab_model(self, uid, normalize_size=False, target_size=1.0): """Download a model from Sketchfab by its UID Parameters: - uid: The unique identifier of the Sketchfab model - normalize_size: If True, scale the model so its largest dimension equals target_size - target_size: The target size in Blender units (meters) for the largest dimension """ try: api_key = self._get_sketchfab_api_key() if not api_key: return {"error": "Sketchfab API key is not configured"} # Use proper authorization header for API key auth headers = { "Authorization": f"Token {api_key}" } # Request download URL using the exact endpoint from the documentation download_endpoint = f"https://api.sketchfab.com/v3/models/{uid}/download" response = requests.get( download_endpoint, headers=headers, timeout=30 # Add timeout of 30 seconds ) if response.status_code == 401: return {"error": "Authentication failed (401). Check your API key."} if response.status_code != 200: return {"error": f"Download request failed with status code {response.status_code}"} data = response.json() # Safety check for None data if data is None: return {"error": "Received empty response from Sketchfab API for download request"} # Extract download URL with safety checks gltf_data = data.get("gltf") if not gltf_data: return {"error": "No gltf download URL available for this model. Response: " + str(data)} download_url = gltf_data.get("url") if not download_url: return {"error": "No download URL available for this model. Make sure the model is downloadable and you have access."} # Download the model (already has timeout) model_response = requests.get(download_url, timeout=60) # 60 second timeout if model_response.status_code != 200: return {"error": f"Model download failed with status code {model_response.status_code}"} # Save to temporary file temp_dir = tempfile.mkdtemp() zip_file_path = os.path.join(temp_dir, f"{uid}.zip") with open(zip_file_path, "wb") as f: f.write(model_response.content) # Extract the zip file with enhanced security with zipfile.ZipFile(zip_file_path, 'r') as zip_ref: # More secure zip slip prevention for file_info in zip_ref.infolist(): # Get the path of the file file_path = file_info.filename # Convert directory separators to the current OS style # This handles both / and \ in zip entries target_path = os.path.join(temp_dir, os.path.normpath(file_path)) # Get absolute paths for comparison abs_temp_dir = os.path.abspath(temp_dir) abs_target_path = os.path.abspath(target_path) # Ensure the normalized path doesn't escape the target directory if not abs_target_path.startswith(abs_temp_dir): with suppress(Exception): shutil.rmtree(temp_dir) return {"error": "Security issue: Zip contains files with path traversal attempt"} # Additional explicit check for directory traversal if ".." in file_path: with suppress(Exception): shutil.rmtree(temp_dir) return {"error": "Security issue: Zip contains files with directory traversal sequence"} # If all files passed security checks, extract them zip_ref.extractall(temp_dir) # Find the main glTF file gltf_files = [f for f in os.listdir(temp_dir) if f.endswith('.gltf') or f.endswith('.glb')] if not gltf_files: with suppress(Exception): shutil.rmtree(temp_dir) return {"error": "No glTF file found in the downloaded model"} main_file = os.path.join(temp_dir, gltf_files[0]) # Import the model bpy.ops.import_scene.gltf(filepath=main_file) # Get the imported objects imported_objects = list(bpy.context.selected_objects) imported_object_names = [obj.name for obj in imported_objects] # Clean up temporary files with suppress(Exception): shutil.rmtree(temp_dir) # Find root objects (objects without parents in the imported set) root_objects = [obj for obj in imported_objects if obj.parent is None] # Helper function to recursively get all mesh children def get_all_mesh_children(obj): """Recursively collect all mesh objects in the hierarchy""" meshes = [] if obj.type == 'MESH': meshes.append(obj) for child in obj.children: meshes.extend(get_all_mesh_children(child)) return meshes # Collect ALL meshes from the entire hierarchy (starting from roots) all_meshes = [] for obj in root_objects: all_meshes.extend(get_all_mesh_children(obj)) if all_meshes: # Calculate combined world bounding box for all meshes all_min = mathutils.Vector((float('inf'), float('inf'), float('inf'))) all_max = mathutils.Vector((float('-inf'), float('-inf'), float('-inf'))) for mesh_obj in all_meshes: # Get world-space bounding box corners for corner in mesh_obj.bound_box: world_corner = mesh_obj.matrix_world @ mathutils.Vector(corner) all_min.x = min(all_min.x, world_corner.x) all_min.y = min(all_min.y, world_corner.y) all_min.z = min(all_min.z, world_corner.z) all_max.x = max(all_max.x, world_corner.x) all_max.y = max(all_max.y, world_corner.y) all_max.z = max(all_max.z, world_corner.z) # Calculate dimensions dimensions = [ all_max.x - all_min.x, all_max.y - all_min.y, all_max.z - all_min.z ] max_dimension = max(dimensions) # Apply normalization if requested scale_applied = 1.0 if normalize_size and max_dimension > 0: scale_factor = target_size / max_dimension scale_applied = scale_factor # ✅ Only apply scale to ROOT objects (not children!) # Child objects inherit parent's scale through matrix_world for root in root_objects: root.scale = ( root.scale.x * scale_factor, root.scale.y * scale_factor, root.scale.z * scale_factor ) # Update the scene to recalculate matrix_world for all objects bpy.context.view_layer.update() # Recalculate bounding box after scaling all_min = mathutils.Vector((float('inf'), float('inf'), float('inf'))) all_max = mathutils.Vector((float('-inf'), float('-inf'), float('-inf'))) for mesh_obj in all_meshes: for corner in mesh_obj.bound_box: world_corner = mesh_obj.matrix_world @ mathutils.Vector(corner) all_min.x = min(all_min.x, world_corner.x) all_min.y = min(all_min.y, world_corner.y) all_min.z = min(all_min.z, world_corner.z) all_max.x = max(all_max.x, world_corner.x) all_max.y = max(all_max.y, world_corner.y) all_max.z = max(all_max.z, world_corner.z) dimensions = [ all_max.x - all_min.x, all_max.y - all_min.y, all_max.z - all_min.z ] world_bounding_box = [[all_min.x, all_min.y, all_min.z], [all_max.x, all_max.y, all_max.z]] else: world_bounding_box = None dimensions = None scale_applied = 1.0 result = { "success": True, "message": "Model imported successfully", "imported_objects": imported_object_names } if world_bounding_box: result["world_bounding_box"] = world_bounding_box if dimensions: result["dimensions"] = [round(d, 4) for d in dimensions] if normalize_size: result["scale_applied"] = round(scale_applied, 6) result["normalized"] = True return result except requests.exceptions.Timeout: return {"error": "Request timed out. Check your internet connection and try again with a simpler model."} except json.JSONDecodeError as e: return {"error": f"Invalid JSON response from Sketchfab API: {str(e)}"} except Exception as e: import traceback traceback.print_exc() return {"error": f"Failed to download model: {str(e)}"} #endregion #region Poly Pizza API def get_polypizza_status(self): """Get the current status of Poly Pizza integration""" enabled = bpy.context.scene.blendermcp_use_polypizza api_key = self._get_polypizza_api_key() if enabled and api_key: return { "enabled": True, "message": "Poly Pizza integration is enabled and ready to use." } elif enabled and not api_key: return { "enabled": False, "message": """Poly Pizza integration is currently enabled, but API key is not given. To enable it: 1. Get a free API key at https://poly.pizza/settings/api 2. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 3. Keep the 'Use Poly Pizza' checkbox checked 4. Enter your Poly Pizza API Key 5. Restart the connection to Claude""" } else: return { "enabled": False, "message": """Poly Pizza integration is currently disabled. To enable it: 1. Get a free API key at https://poly.pizza/settings/api 2. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 3. Check the 'Use assets from Poly Pizza' checkbox 4. Enter your Poly Pizza API Key 5. Restart the connection to Claude""" } def search_polypizza_models(self, query=None, category=None, licence=None, animated=False, limit=20, page=None): """Search for models on Poly Pizza by keyword and/or filters Parameters: - query: Keyword to search for. When omitted, at least one filter is required: the bare /search endpoint answers 400 without one. - category: Numeric category id (0-11); the MCP server resolves names - licence: Numeric licence id (0 = CC-BY, 1 = CC0); the MCP server resolves names - animated: When True, return only animated models - limit: Maximum number of results to return (the API caps a page at 32) - page: Optional 0-based page number """ try: api_key = self._get_polypizza_api_key() if not api_key: return {"error": "Poly Pizza API key is not configured"} try: filters = _polypizza_filter_params(category, licence, animated) except ValueError as e: return {"error": str(e)} keyword = (query or "").strip() if not keyword and not filters: return {"error": ( "Poly Pizza needs a search keyword or at least one filter " "(category, licence, or animated=True). An unfiltered listing of the " "whole catalogue is rejected by the API with HTTP 400." )} # Limit and Page are Capitalized like the filters: lowercase # variants are silently ignored and the API then serves its # default page of 32. params = dict(filters) params["Limit"] = max(1, min(int(limit), 32)) if page is not None: params["Page"] = page headers = dict(REQ_HEADERS) headers["x-auth-token"] = api_key if keyword: url = f"{POLYPIZZA_API_BASE}/search/{quote(keyword, safe='')}" else: url = f"{POLYPIZZA_API_BASE}/search" response = requests.get(url, headers=headers, params=params, timeout=30) if response.status_code in (401, 403): return {"error": f"Poly Pizza authentication failed ({response.status_code}). Check your API key."} if response.status_code == 400: return {"error": ( "Poly Pizza rejected the search parameters (400). Category must be an id in " "0-11 and licence 0 (CC-BY) or 1 (CC0)." )} if response.status_code == 429: return {"error": "Poly Pizza rate limit exceeded (100 requests/second). Try again in a moment."} if response.status_code != 200: return {"error": f"Poly Pizza API request failed with status code {response.status_code}"} response_data = response.json() if response_data is None: return {"error": "Received empty response from Poly Pizza API"} results = response_data.get("results", []) if not isinstance(results, list): return {"error": f"Unexpected response format from Poly Pizza API: {response_data}"} return { "total": response_data.get("total", len(results)), "results": [_polypizza_summarize_model(m) for m in results if isinstance(m, dict)], "filters_applied": filters, } except requests.exceptions.Timeout: return {"error": "Request timed out. Check your internet connection."} except json.JSONDecodeError as e: return {"error": f"Invalid JSON response from Poly Pizza API: {str(e)}"} except Exception as e: import traceback traceback.print_exc() return {"error": str(e)} def download_polypizza_model(self, model_id, normalize_size=False, target_size=1.0): """Download a model from Poly Pizza by its ID Parameters: - model_id: The Poly Pizza model ID (from search_polypizza_models) - normalize_size: If True, scale the model so its largest dimension equals target_size - target_size: The target size in Blender units (meters) for the largest dimension """ temp_dir = None try: api_key = self._get_polypizza_api_key() if not api_key: return {"error": "Poly Pizza API key is not configured"} headers = dict(REQ_HEADERS) headers["x-auth-token"] = api_key response = requests.get( f"{POLYPIZZA_API_BASE}/model/{quote(str(model_id), safe='')}", headers=headers, timeout=30 ) if response.status_code in (401, 403): return {"error": f"Poly Pizza authentication failed ({response.status_code}). Check your API key."} if response.status_code == 404: return {"error": f"No Poly Pizza model found with ID '{model_id}'"} if response.status_code != 200: return {"error": f"Poly Pizza model lookup failed with status code {response.status_code}"} model = response.json() if not isinstance(model, dict): return {"error": f"Unexpected response format from Poly Pizza API: {model}"} download_url = model.get("Download") if not download_url: return {"error": f"Poly Pizza model '{model_id}' has no downloadable GLB file"} # The CDN takes no API key and must never be sent one: it is a # separate host from the API. file_response = requests.get(download_url, headers=dict(REQ_HEADERS), timeout=60) cdn_error = _polypizza_cdn_error( file_response.status_code, getattr(file_response, "headers", None), file_response.content or b"", ) if cdn_error: return {"error": cdn_error} # Every Poly Pizza model is a single self-contained .glb - no zip, # no sidecar textures - so it goes straight to disk and into glTF import. safe_id = re.sub(r"[^A-Za-z0-9_-]", "_", str(model_id)) or "model" temp_dir = tempfile.mkdtemp() glb_path = os.path.join(temp_dir, f"{safe_id}.glb") with open(glb_path, "wb") as f: f.write(file_response.content) bpy.ops.import_scene.gltf(filepath=glb_path) # Get the imported objects imported_objects = list(bpy.context.selected_objects) imported_object_names = [obj.name for obj in imported_objects] # Clean up temporary files with suppress(Exception): shutil.rmtree(temp_dir) temp_dir = None # Find root objects (objects without parents in the imported set) root_objects = [obj for obj in imported_objects if obj.parent is None] # 69% of the catalogue is CC-BY, so the credit line has to outlive # the session. Custom properties are saved into the .blend. attribution = model.get("Attribution") or "" licence = model.get("Licence") or "" for root in root_objects: root["polypizza_attribution"] = attribution root["polypizza_id"] = model.get("ID") or str(model_id) root["polypizza_licence"] = licence # Helper function to recursively get all mesh children def get_all_mesh_children(obj): """Recursively collect all mesh objects in the hierarchy""" meshes = [] if obj.type == 'MESH': meshes.append(obj) for child in obj.children: meshes.extend(get_all_mesh_children(child)) return meshes # Collect ALL meshes from the entire hierarchy (starting from roots) all_meshes = [] for obj in root_objects: all_meshes.extend(get_all_mesh_children(obj)) if all_meshes: # Calculate combined world bounding box for all meshes all_min = mathutils.Vector((float('inf'), float('inf'), float('inf'))) all_max = mathutils.Vector((float('-inf'), float('-inf'), float('-inf'))) for mesh_obj in all_meshes: # Get world-space bounding box corners for corner in mesh_obj.bound_box: world_corner = mesh_obj.matrix_world @ mathutils.Vector(corner) all_min.x = min(all_min.x, world_corner.x) all_min.y = min(all_min.y, world_corner.y) all_min.z = min(all_min.z, world_corner.z) all_max.x = max(all_max.x, world_corner.x) all_max.y = max(all_max.y, world_corner.y) all_max.z = max(all_max.z, world_corner.z) # Calculate dimensions dimensions = [ all_max.x - all_min.x, all_max.y - all_min.y, all_max.z - all_min.z ] max_dimension = max(dimensions) # Apply normalization if requested scale_applied = 1.0 if normalize_size and max_dimension > 0: scale_factor = target_size / max_dimension scale_applied = scale_factor # Only apply scale to ROOT objects (not children!) # Child objects inherit parent's scale through matrix_world for root in root_objects: root.scale = ( root.scale.x * scale_factor, root.scale.y * scale_factor, root.scale.z * scale_factor ) # Update the scene to recalculate matrix_world for all objects bpy.context.view_layer.update() # Recalculate bounding box after scaling all_min = mathutils.Vector((float('inf'), float('inf'), float('inf'))) all_max = mathutils.Vector((float('-inf'), float('-inf'), float('-inf'))) for mesh_obj in all_meshes: for corner in mesh_obj.bound_box: world_corner = mesh_obj.matrix_world @ mathutils.Vector(corner) all_min.x = min(all_min.x, world_corner.x) all_min.y = min(all_min.y, world_corner.y) all_min.z = min(all_min.z, world_corner.z) all_max.x = max(all_max.x, world_corner.x) all_max.y = max(all_max.y, world_corner.y) all_max.z = max(all_max.z, world_corner.z) dimensions = [ all_max.x - all_min.x, all_max.y - all_min.y, all_max.z - all_min.z ] world_bounding_box = [[all_min.x, all_min.y, all_min.z], [all_max.x, all_max.y, all_max.z]] else: world_bounding_box = None dimensions = None scale_applied = 1.0 result = { "success": True, "message": "Model imported successfully", "imported_objects": imported_object_names, "model_id": model.get("ID") or str(model_id), "title": model.get("Title"), "licence": licence, "attribution": attribution, "tri_count": model.get("Tri Count"), } if world_bounding_box: result["world_bounding_box"] = world_bounding_box if dimensions: result["dimensions"] = [round(d, 4) for d in dimensions] if normalize_size: result["scale_applied"] = round(scale_applied, 6) result["normalized"] = True return result except requests.exceptions.Timeout: return {"error": "Request timed out. Check your internet connection and try again."} except json.JSONDecodeError as e: return {"error": f"Invalid JSON response from Poly Pizza API: {str(e)}"} except Exception as e: import traceback traceback.print_exc() return {"error": f"Failed to download model: {str(e)}"} finally: if temp_dir: with suppress(Exception): shutil.rmtree(temp_dir) #endregion #region Hunyuan3D def get_hunyuan3d_status(self): """Get the current status of Hunyuan3D integration""" if premium_active(): return premium_integration_status("hunyuan3d", bpy.context.scene.blendermcp_use_hunyuan3d) enabled = bpy.context.scene.blendermcp_use_hunyuan3d hunyuan3d_mode = bpy.context.scene.blendermcp_hunyuan3d_mode secret_id = self._get_hunyuan3d_secret_id() secret_key = self._get_hunyuan3d_secret_key() api_url = self._get_hunyuan3d_api_url() if enabled: match hunyuan3d_mode: case "OFFICIAL_API": if not secret_id or not secret_key: return { "enabled": False, "mode": hunyuan3d_mode, "message": """Hunyuan3D integration is currently enabled, but SecretId or SecretKey is not given. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Keep the 'Use Tencent Hunyuan 3D model generation' checkbox checked 3. Choose the right platform and fill in the SecretId and SecretKey 4. Restart the connection to Claude""" } case "LOCAL_API": if not api_url: return { "enabled": False, "mode": hunyuan3d_mode, "message": """Hunyuan3D integration is currently enabled, but API URL is not given. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Keep the 'Use Tencent Hunyuan 3D model generation' checkbox checked 3. Choose the right platform and fill in the API URL 4. Restart the connection to Claude""" } case _: return { "enabled": False, "message": "Hunyuan3D integration is enabled and mode is not supported." } return { "enabled": True, "mode": hunyuan3d_mode, "message": "Hunyuan3D integration is enabled and ready to use." } return { "enabled": False, "message": """Hunyuan3D integration is currently disabled. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Check the 'Use Tencent Hunyuan 3D model generation' checkbox 3. Restart the connection to Claude""" } @staticmethod def get_tencent_cloud_sign_headers( method: str, path: str, headParams: dict, data: dict, service: str, region: str, secret_id: str, secret_key: str, host: str = None ): """Generate the signature header required for Tencent Cloud API requests headers""" # Generate timestamp timestamp = int(time.time()) date = datetime.utcfromtimestamp(timestamp).strftime("%Y-%m-%d") # If host is not provided, it is generated based on service and region. if not host: host = f"{service}.tencentcloudapi.com" endpoint = f"https://{host}" # Constructing the request body payload_str = json.dumps(data) # ************* Step 1: Concatenate the canonical request string ************* canonical_uri = path canonical_querystring = "" ct = "application/json; charset=utf-8" canonical_headers = f"content-type:{ct}\nhost:{host}\nx-tc-action:{headParams.get('Action', '').lower()}\n" signed_headers = "content-type;host;x-tc-action" hashed_request_payload = hashlib.sha256(payload_str.encode("utf-8")).hexdigest() canonical_request = (method + "\n" + canonical_uri + "\n" + canonical_querystring + "\n" + canonical_headers + "\n" + signed_headers + "\n" + hashed_request_payload) # ************* Step 2: Construct the reception signature string ************* credential_scope = f"{date}/{service}/tc3_request" hashed_canonical_request = hashlib.sha256(canonical_request.encode("utf-8")).hexdigest() string_to_sign = ("TC3-HMAC-SHA256" + "\n" + str(timestamp) + "\n" + credential_scope + "\n" + hashed_canonical_request) # ************* Step 3: Calculate the signature ************* def sign(key, msg): return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest() secret_date = sign(("TC3" + secret_key).encode("utf-8"), date) secret_service = sign(secret_date, service) secret_signing = sign(secret_service, "tc3_request") signature = hmac.new( secret_signing, string_to_sign.encode("utf-8"), hashlib.sha256 ).hexdigest() # ************* Step 4: Connect Authorization ************* authorization = ("TC3-HMAC-SHA256" + " " + "Credential=" + secret_id + "/" + credential_scope + ", " + "SignedHeaders=" + signed_headers + ", " + "Signature=" + signature) # Constructing request headers headers = { "Authorization": authorization, "Content-Type": "application/json; charset=utf-8", "Host": host, "X-TC-Action": headParams.get("Action", ""), "X-TC-Timestamp": str(timestamp), "X-TC-Version": headParams.get("Version", ""), "X-TC-Region": region } return headers, endpoint def create_hunyuan_job(self, *args, quality=None, **kwargs): # quality is Premium-only; your own Tencent key has no such option. if premium_active(): return premium_create_hunyuan_job(*args, quality=quality, **kwargs) match bpy.context.scene.blendermcp_hunyuan3d_mode: case "OFFICIAL_API": return self.create_hunyuan_job_main_site(*args, **kwargs) case "LOCAL_API": return self.create_hunyuan_job_local_site(*args, **kwargs) case _: return f"Error: Unknown Hunyuan3D mode!" def create_hunyuan_job_main_site( self, text_prompt: str = None, image: str = None ): try: secret_id = self._get_hunyuan3d_secret_id() secret_key = self._get_hunyuan3d_secret_key() if not secret_id or not secret_key: return {"error": "SecretId or SecretKey is not given"} # Parameter verification if not text_prompt and not image: return {"error": "Prompt or Image is required"} if text_prompt and image: return {"error": "Prompt and Image cannot be provided simultaneously"} profile = hunyuan_api_profile( getattr(bpy.context.scene, "blendermcp_hunyuan3d_intl_pro", False)) service = profile["service"] action = profile["submit_action"] version = profile["version"] region = profile["region"] headParams={ "Action": action, "Version": version, "Region": region, } # Constructing request parameters data = profile["submit_body"] # Handling text prompts if text_prompt: if len(text_prompt) > 1024: return {"error": "Prompt exceeds 1024 characters limit"} data["Prompt"] = text_prompt # Handling image if image: if re.match(r'^https?://', image, re.IGNORECASE) is not None: data["ImageUrl"] = image else: try: # Convert to Base64 format image_base64 = base64.b64encode(_read_image_file(image)).decode("ascii") data["ImageBase64"] = image_base64 except Exception as e: return {"error": f"Image encoding failed: {str(e)}"} # Get signed headers headers, endpoint = self.get_tencent_cloud_sign_headers("POST", "/", headParams, data, service, region, secret_id, secret_key) response = requests.post( endpoint, headers = headers, data = json.dumps(data), timeout=30, ) if response.status_code == 200: return response.json() return { "error": f"API request failed with status {response.status_code}: {response}" } except Exception as e: return {"error": str(e)} def create_hunyuan_job_local_site( self, text_prompt: str = None, image: str = None): try: base_url = self._get_hunyuan3d_api_url().rstrip('/') octree_resolution = bpy.context.scene.blendermcp_hunyuan3d_octree_resolution num_inference_steps = bpy.context.scene.blendermcp_hunyuan3d_num_inference_steps guidance_scale = bpy.context.scene.blendermcp_hunyuan3d_guidance_scale texture = bpy.context.scene.blendermcp_hunyuan3d_texture if not base_url: return {"error": "API URL is not given"} # Parameter verification if not text_prompt and not image: return {"error": "Prompt or Image is required"} # Constructing request parameters data = { "octree_resolution": octree_resolution, "num_inference_steps": num_inference_steps, "guidance_scale": guidance_scale, "texture": texture, } # Handling text prompts if text_prompt: data["text"] = text_prompt # Handling image if image: if re.match(r'^https?://', image, re.IGNORECASE) is not None: try: image_base64 = base64.b64encode(_fetch_public_image(image)).decode("ascii") data["image"] = image_base64 except Exception as e: return {"error": f"Failed to download or encode image: {str(e)}"} else: try: # Convert to Base64 format image_base64 = base64.b64encode(_read_image_file(image)).decode("ascii") data["image"] = image_base64 except Exception as e: return {"error": f"Image encoding failed: {str(e)}"} # The local server generates synchronously, so allow it minutes to reply. response = requests.post( f"{base_url}/generate", json = data, timeout=(10, 600), ) if response.status_code != 200: return { "error": f"Generation failed: {response.text}" } # Decode base64 and save to temporary file with tempfile.NamedTemporaryFile(delete=False, suffix=".glb") as temp_file: temp_file.write(response.content) temp_file_name = temp_file.name # Import the GLB file in the main thread def import_handler(): bpy.ops.import_scene.gltf(filepath=temp_file_name) os.unlink(temp_file.name) return None bpy.app.timers.register(import_handler) return { "status": "DONE", "message": "Generation and Import glb succeeded" } except Exception as e: print(f"An error occurred: {e}") return {"error": str(e)} def poll_hunyuan_job_status(self, *args, **kwargs): if premium_active(): return premium_poll_hunyuan_job_status(*args, **kwargs) return self.poll_hunyuan_job_status_ai(*args, **kwargs) def poll_hunyuan_job_status_ai(self, job_id: str): """Call the job status API to get the job status""" print(job_id) try: secret_id = self._get_hunyuan3d_secret_id() secret_key = self._get_hunyuan3d_secret_key() if not secret_id or not secret_key: return {"error": "SecretId or SecretKey is not given"} if not job_id: return {"error": "JobId is required"} profile = hunyuan_api_profile( getattr(bpy.context.scene, "blendermcp_hunyuan3d_intl_pro", False)) service = profile["service"] action = profile["query_action"] version = profile["version"] region = profile["region"] headParams={ "Action": action, "Version": version, "Region": region, } clean_job_id = job_id.removeprefix("job_") data = { "JobId": clean_job_id } headers, endpoint = self.get_tencent_cloud_sign_headers("POST", "/", headParams, data, service, region, secret_id, secret_key) response = requests.post( endpoint, headers=headers, data=json.dumps(data), timeout=30, ) if response.status_code == 200: return response.json() return { "error": f"API request failed with status {response.status_code}: {response}" } except Exception as e: return {"error": str(e)} def import_generated_asset_hunyuan(self, *args, **kwargs): if premium_active(): return premium_import_generated_asset_hunyuan(*args, **kwargs) return self.import_generated_asset_hunyuan_ai(*args, **kwargs) def _import_hunyuan_glb(self, name: str, glb_url: str): temp_dir = tempfile.mkdtemp(prefix="hunyuan_glb_") glb_path = osp.join(temp_dir, "model.glb") try: glb_response = requests.get(glb_url, stream=True, timeout=120) glb_response.raise_for_status() with open(glb_path, "wb") as f: for chunk in glb_response.iter_content(chunk_size=8192): f.write(chunk) bpy.ops.import_scene.gltf(filepath=glb_path) imported_objs = [obj for obj in bpy.context.selected_objects if obj.type == 'MESH'] if not imported_objs: return {"succeed": False, "error": "No mesh objects imported from GLB"} obj = imported_objs[0] if name: obj.name = name result = { "name": obj.name, "type": obj.type, "location": [obj.location.x, obj.location.y, obj.location.z], "rotation": [obj.rotation_euler.x, obj.rotation_euler.y, obj.rotation_euler.z], "scale": [obj.scale.x, obj.scale.y, obj.scale.z], } if obj.type == "MESH": result["world_bounding_box"] = self._get_aabb(obj) return {"succeed": True, **result} except Exception as e: return {"succeed": False, "error": str(e)} finally: with suppress(Exception): shutil.rmtree(temp_dir) def import_generated_asset_hunyuan_ai(self, name: str, zip_file_url: str): if not zip_file_url: return {"error": "No file URL provided"} # Validate URL if not re.match(r'^https?://', zip_file_url, re.IGNORECASE): return {"error": "Invalid URL format. Must start with http:// or https://"} # Prefer GLB (self-contained with materials) over OBJ/ZIP (API 3.0 returns .glb URLs) url_path = zip_file_url.split('?', 1)[0].split('#', 1)[0].lower() if url_path.endswith('.glb'): return self._import_hunyuan_glb(name, zip_file_url) # Fallback: ZIP/OBJ import (legacy) temp_dir = tempfile.mkdtemp(prefix="tencent_obj_") zip_file_path = osp.join(temp_dir, "model.zip") obj_file_path = osp.join(temp_dir, "model.obj") try: zip_response = requests.get(zip_file_url, stream=True, timeout=120) zip_response.raise_for_status() with open(zip_file_path, "wb") as f: for chunk in zip_response.iter_content(chunk_size=8192): f.write(chunk) with zipfile.ZipFile(zip_file_path, "r") as zip_ref: # Mirror the Sketchfab zip-slip checks before extractall. abs_temp_dir = os.path.abspath(temp_dir) for file_info in zip_ref.infolist(): file_path = file_info.filename target_path = os.path.join(temp_dir, os.path.normpath(file_path)) abs_target_path = os.path.abspath(target_path) if not abs_target_path.startswith(abs_temp_dir + os.sep) and abs_target_path != abs_temp_dir: return { "succeed": False, "error": "Security issue: Zip contains files with path traversal attempt", } if ".." in file_path: return { "succeed": False, "error": "Security issue: Zip contains files with directory traversal sequence", } zip_ref.extractall(temp_dir) for file in os.listdir(temp_dir): if file.endswith(".obj"): obj_file_path = osp.join(temp_dir, file) if not osp.exists(obj_file_path): return {"succeed": False, "error": "OBJ file not found after extraction"} if bpy.app.version>=(4, 0, 0): bpy.ops.wm.obj_import(filepath=obj_file_path) else: bpy.ops.import_scene.obj(filepath=obj_file_path) imported_objs = [obj for obj in bpy.context.selected_objects if obj.type == 'MESH'] if not imported_objs: return {"succeed": False, "error": "No mesh objects imported"} obj = imported_objs[0] if name: obj.name = name result = { "name": obj.name, "type": obj.type, "location": [obj.location.x, obj.location.y, obj.location.z], "rotation": [obj.rotation_euler.x, obj.rotation_euler.y, obj.rotation_euler.z], "scale": [obj.scale.x, obj.scale.y, obj.scale.z], } if obj.type == "MESH": result["world_bounding_box"] = self._get_aabb(obj) return {"succeed": True, **result} except Exception as e: return {"succeed": False, "error": str(e)} finally: with suppress(Exception): shutil.rmtree(temp_dir) #endregion #region Tripo def get_tripo_status(self): """Get the current status of Tripo integration.""" if premium_active(): return premium_integration_status("tripo", getattr(bpy.context.scene, "blendermcp_use_tripo", False)) if not getattr(bpy.context.scene, "blendermcp_use_tripo", False): return { "enabled": False, "message": """Tripo integration is currently disabled. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Under AI Model Generation, check Tripo 3. Choose a model and fill in the API Key""", } if not self._get_tripo_api_key(): return { "enabled": False, "message": """Tripo integration is currently enabled, but the API key is not given. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Under AI Model Generation, keep Tripo checked 3. Choose a model and fill in the API Key""", } model, error = self._resolve_tripo_model() if error: return {"enabled": False, "message": error["error"]} choices = ", ".join(f"{label} ({ident})" for ident, label in TRIPO_MODELS.items()) return { "enabled": True, "model": model, "message": ( f"Tripo integration is enabled and ready to use. Model: {TRIPO_MODELS[model]}. " f"Sidebar choices: {choices}." ), } def _tripo_headers(self): api_key = self._get_tripo_api_key() if not api_key: return None, {"error": "Tripo API key is not given"} return {**TRIPO_HEADERS, "Authorization": f"Bearer {api_key}"}, None @staticmethod def _tripo_parse(response): """(data, None) on success, else (None, {"error": readable message}). Messages come from fixed text or Tripo's reply, never the request, so the key can't leak into them.""" try: payload = response.json() except Exception: payload = None if not isinstance(payload, dict): payload = None code = payload.get("code") if payload else None message = payload.get("message") if payload else None message = message.strip() if isinstance(message, str) and message.strip() else None suggestion = payload.get("suggestion") if payload else None suggestion = suggestion.strip() if isinstance(suggestion, str) and suggestion.strip() else None if message and suggestion and suggestion not in message: joiner = "" if message[-1] in ".!?" else ". " message = f"{message}{joiner}{suggestion}" # 401, 1000 and 1001 can echo the key, so ignore the body. if response.status_code == 401 or code in (1000, 1001): return None, {"error": "Tripo rejected the API key"} if code == 2010: return None, {"error": message or f"Out of Tripo credits. Top up at tripo3d.{tripo_endpoints()['domain']}"} if code == 2000: return None, {"error": message or "Tripo concurrency limit hit, wait and retry"} if code == 1007 or response.status_code == 429: return None, {"error": message or "Tripo rate limit hit, wait and retry"} if response.status_code == 403: return None, {"error": message or "Tripo refused the request: no permission, or not enough credits"} if response.status_code == 404: return None, {"error": message or "Tripo could not find that resource"} if response.status_code == 500: return None, {"error": message or "Tripo request failed. Try again later"} if not response.ok or payload is None: return None, {"error": message or f"Tripo request failed with status {response.status_code}"} if code not in (0, None): return None, {"error": message or "Tripo request failed"} data = payload.get("data") if not isinstance(data, dict): return None, {"error": "Tripo response did not include data"} return data, None def _tripo_post(self, path, body, files=None): headers, error = self._tripo_headers() if error: return None, error try: response = requests.post( f"{tripo_endpoints()['api']}{path}", headers=headers, json=body, files=files, timeout=TRIPO_TIMEOUT) except Exception: return None, {"error": "Tripo request failed. Check the internet connection and try again"} return self._tripo_parse(response) def _tripo_upload_image(self, path, headers): if not os.path.isfile(path): return None, {"error": f"Image file not found: {path}"} mime = TRIPO_IMAGE_TYPES.get(os.path.splitext(path)[1].lower()) if not mime: return None, {"error": "Tripo accepts JPEG or PNG images"} if os.path.getsize(path) > TRIPO_IMAGE_MAX_BYTES: return None, {"error": "Tripo accepts images up to 20 MB"} try: with open(path, "rb") as handle: response = requests.post( f"{tripo_endpoints()['api']}/files", headers=headers, files={"file": (os.path.basename(path), handle, mime)}, timeout=TRIPO_TIMEOUT, ) except Exception: return None, {"error": "Tripo request failed. Check the internet connection and try again"} data, error = self._tripo_parse(response) if error: return None, error file_token = data.get("file_token") if not file_token: return None, {"error": "Tripo upload did not return a file_token"} return file_token, None def create_tripo_job(self, text_prompt=None, image=None, quality=None): """Start one Tripo text-to-model or image-to-model task. quality is Premium-only.""" text_prompt = (text_prompt or "").strip() image = (image or "").strip() if bool(text_prompt) == bool(image): return {"error": "Provide either a text prompt or an image, not both"} if len(text_prompt) > TRIPO_PROMPT_MAX: return {"error": f"Tripo prompts are limited to {TRIPO_PROMPT_MAX} characters"} model, error = self._resolve_tripo_model() if error: return error headers, error = self._tripo_headers() if error: return error if text_prompt: data, error = self._tripo_post( "/generation/text-to-model", {"model": model, "prompt": text_prompt, "texture": True, "pbr": True}, ) else: if re.match(r"^https?://", image, re.IGNORECASE): tripo_input = image else: tripo_input, error = self._tripo_upload_image(image, headers) if error: return error data, error = self._tripo_post( "/generation/image-to-model", {"model": model, "input": tripo_input, "texture": True, "pbr": True}, ) if error: return error task_id = data.get("task_id") if not task_id: return {"error": "Tripo response did not include a task id"} return {"task_id": task_id, "model": model} def poll_tripo_job_status(self, task_id=None, request_id=None): """Query one Tripo task. Does not wait; the MCP client polls again.""" if not task_id: return {"error": "task_id is required"} headers, error = self._tripo_headers() if error: return error try: response = requests.get( f"{tripo_endpoints()['api']}/tasks/{quote(str(task_id), safe='')}", headers=headers, timeout=TRIPO_TIMEOUT, ) except Exception: return {"error": "Tripo request failed. Check the internet connection and try again"} data, error = self._tripo_parse(response) if error: return error result = { "task_id": data.get("task_id", task_id), "status": data.get("status"), "progress": data.get("progress"), } status = data.get("status") if status == "success": output = data.get("output") or {} model_url = output.get("model_url") or output.get("pbr_model") or output.get("model") if not model_url: return {**result, "error": "Tripo task succeeded but returned no model URL"} result["model_url"] = model_url elif status in ("failed", "cancelled", "banned", "expired"): result["error"] = data.get("error_message") or data.get("message") or data.get("error") or status return result def import_generated_asset_tripo(self, name, model_url=None, request_id=None): """Download a Tripo GLB and import it into the current scene.""" if not model_url: return {"succeed": False, "error": "No file URL provided"} if not re.match(r"^https?://", model_url, re.IGNORECASE): return {"succeed": False, "error": "Invalid URL format. Must start with http:// or https://"} temp_dir = tempfile.mkdtemp(prefix="tripo_glb_") glb_path = osp.join(temp_dir, "model.glb") try: response = requests.get(model_url, headers=TRIPO_HEADERS, stream=True, timeout=TRIPO_TIMEOUT) response.raise_for_status() with open(glb_path, "wb") as handle: for chunk in response.iter_content(chunk_size=8192): handle.write(chunk) obj = self._clean_imported_glb(filepath=glb_path, mesh_name=name) if obj is None: return {"succeed": False, "error": "No mesh objects imported from GLB"} result = { "name": obj.name, "type": obj.type, "location": [obj.location.x, obj.location.y, obj.location.z], "rotation": [obj.rotation_euler.x, obj.rotation_euler.y, obj.rotation_euler.z], "scale": [obj.scale.x, obj.scale.y, obj.scale.z], } if obj.type == "MESH": result["world_bounding_box"] = self._get_aabb(obj) return {"succeed": True, **result} except Exception: return {"succeed": False, "error": "Failed to import Tripo model"} finally: with suppress(Exception): shutil.rmtree(temp_dir) #endregion #region Meshy def get_meshy_status(self): """Get the current status of Meshy integration.""" if premium_active(): return premium_integration_status("meshy", getattr(bpy.context.scene, "blendermcp_use_meshy", False)) if not getattr(bpy.context.scene, "blendermcp_use_meshy", False): return { "enabled": False, "message": """Meshy integration is currently disabled. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Under AI Model Generation, check Meshy 3. Choose a model and fill in the API Key (needs a paid Meshy plan)""", } if not self._get_meshy_api_key(): return { "enabled": False, "message": """Meshy integration is currently enabled, but the API key is not given. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Under AI Model Generation, keep Meshy checked 3. Fill in the API Key (needs a paid Meshy plan)""", } model, error = self._resolve_meshy_model() if error: return {"enabled": False, "message": error["error"]} choices = ", ".join(f"{label} ({ident})" for ident, label in MESHY_MODELS.items()) return { "enabled": True, "model": model, "message": ( f"Meshy integration is enabled and ready to use. Model: {MESHY_MODELS[model]}. " f"Sidebar choices: {choices}." ), } def _meshy_headers(self): api_key = self._get_meshy_api_key() if not api_key: return None, {"error": "Meshy API key is not given"} return {**MESHY_HEADERS, "Authorization": f"Bearer {api_key}"}, None @staticmethod def _meshy_parse(response): """(payload, None) on success, else (None, {"error": readable message}). Messages come from fixed text or Meshy's reply, never the request, so the key can't leak into them.""" try: payload = response.json() except Exception: payload = None if response.ok and isinstance(payload, dict): return payload, None if response.status_code == 401: return None, {"error": "Meshy rejected the API key"} # 402 also means a key credit limit, a workspace limit or a free plan, # so Meshy's own message wins; the fixed text is only a fallback. fallback = { 402: "Out of Meshy credits. Top up at meshy.ai", 429: "Meshy rate limit hit, wait and retry", }.get(response.status_code, f"Meshy request failed with status {response.status_code}") message = payload.get("message") if isinstance(payload, dict) else None return None, {"error": message or fallback} def _meshy_post(self, path, body): headers, error = self._meshy_headers() if error: return None, error try: response = requests.post(f"{MESHY_API_BASE}{path}", headers=headers, json=body, timeout=MESHY_TIMEOUT) except Exception: return None, {"error": "Meshy request failed. Check the internet connection and try again"} data, error = self._meshy_parse(response) if error: return None, error task_id = data.get("result") if not task_id: return None, {"error": "Meshy response did not include a task id"} return task_id, None @staticmethod def _meshy_image_url(image): """A URL or data URI as given; a local file as a base64 data URI.""" if re.match(r"^(https?://|data:image/)", image, re.IGNORECASE): return image, None if not os.path.isfile(image): return None, {"error": f"Image file not found: {image}"} mime = MESHY_IMAGE_TYPES.get(os.path.splitext(image)[1].lower()) if not mime: return None, {"error": "Meshy accepts JPG, PNG or WebP images"} if os.path.getsize(image) > MESHY_IMAGE_MAX_BYTES: return None, {"error": "Meshy accepts images up to 20 MB"} with open(image, "rb") as handle: encoded = base64.b64encode(handle.read()).decode("ascii") return f"data:{mime};base64,{encoded}", None def create_meshy_job(self, text_prompt=None, image=None, pose_mode=None): """Start a Meshy text preview task ("t2p") or image-to-3D task ("i2m").""" text_prompt = (text_prompt or "").strip() image = (image or "").strip() if bool(text_prompt) == bool(image): return {"error": "Provide either a text prompt or an image, not both"} if len(text_prompt) > MESHY_PROMPT_MAX: return {"error": f"Meshy prompts are limited to {MESHY_PROMPT_MAX} characters"} if pose_mode and pose_mode not in MESHY_POSES: return {"error": "pose_mode must be 'a-pose' or 't-pose'"} model, error = self._resolve_meshy_model() if error: return error if text_prompt: body = {"mode": "preview", "prompt": text_prompt, "ai_model": model, **MESHY_OUTPUT} if pose_mode: body["pose_mode"] = pose_mode task_id, error = self._meshy_post("/v2/text-to-3d", body) kind = "t2p" else: image_url, error = self._meshy_image_url(image) if error: return error body = {"image_url": image_url, "ai_model": model, "should_texture": True, "enable_pbr": True, **MESHY_OUTPUT} if pose_mode: body["pose_mode"] = pose_mode task_id, error = self._meshy_post("/v1/image-to-3d", body) kind = "i2m" if error: return error return {"task_id": task_id, "kind": kind, "model": model} def refine_meshy_job(self, preview_task_id=None): """Texture a finished preview. At most one refine per preview: asking again returns the refine already started.""" if not preview_task_id: return {"error": "preview_task_id is required"} if preview_task_id in _meshy_refines: return {"task_id": _meshy_refines[preview_task_id], "kind": "t2r"} body = {"mode": "refine", "preview_task_id": preview_task_id, "enable_pbr": True, **MESHY_OUTPUT} task_id, error = self._meshy_post("/v2/text-to-3d", body) if error: return error _meshy_refines[preview_task_id] = task_id return {"task_id": task_id, "kind": "t2r"} def poll_meshy_job_status(self, task_id=None, kind=None): """Query one Meshy task. Does not wait; the MCP client polls again.""" if not task_id: return {"error": "task_id is required"} if kind == "prm": return {"error": "This Meshy generation was started through Premium. Switch Generation Source " "back to Premium in the add-on preferences to finish it."} path = {"t2p": "/v2/text-to-3d", "t2r": "/v2/text-to-3d", "i2m": "/v1/image-to-3d"}.get(kind) if not path: return {"error": f"Unknown Meshy task kind: {kind}"} headers, error = self._meshy_headers() if error: return error try: response = requests.get(f"{MESHY_API_BASE}{path}/{quote(str(task_id), safe='')}", headers=headers, timeout=MESHY_TIMEOUT) except Exception: return {"error": "Meshy request failed. Check the internet connection and try again"} data, error = self._meshy_parse(response) if error: return error result = {"status": data.get("status"), "progress": data.get("progress")} if data.get("status") == "SUCCEEDED": model_url = (data.get("model_urls") or {}).get("glb") if not model_url: return {**result, "error": "Meshy task succeeded but returned no GLB URL"} result["model_url"] = model_url elif data.get("status") in ("FAILED", "CANCELED"): result["error"] = (data.get("task_error") or {}).get("message") or data.get("status") return result def import_generated_asset_meshy(self, name, model_url=None): """Download a Meshy GLB and import it into the current scene.""" if not model_url: return {"succeed": False, "error": "No file URL provided"} if not re.match(r"^https?://", model_url, re.IGNORECASE): return {"succeed": False, "error": "Invalid URL format. Must start with http:// or https://"} temp_dir = tempfile.mkdtemp(prefix="meshy_glb_") glb_path = osp.join(temp_dir, "model.glb") try: response = requests.get(model_url, headers=MESHY_HEADERS, stream=True, timeout=MESHY_TIMEOUT) response.raise_for_status() with open(glb_path, "wb") as handle: for chunk in response.iter_content(chunk_size=8192): handle.write(chunk) obj = self._clean_imported_glb(filepath=glb_path, mesh_name=name) if obj is None: return {"succeed": False, "error": "No mesh objects imported from GLB"} result = { "name": obj.name, "type": obj.type, "location": [obj.location.x, obj.location.y, obj.location.z], "rotation": [obj.rotation_euler.x, obj.rotation_euler.y, obj.rotation_euler.z], "scale": [obj.scale.x, obj.scale.y, obj.scale.z], } if obj.type == "MESH": result["world_bounding_box"] = self._get_aabb(obj) return {"succeed": True, **result} except Exception: return {"succeed": False, "error": "Failed to import Meshy model"} finally: with suppress(Exception): shutil.rmtree(temp_dir) #endregion #region World Labs def get_worldlabs_status(self): """Get the current status of World Labs integration.""" enabled = getattr(bpy.context.scene, "blendermcp_use_worldlabs", False) if not worldlabs_supported(): return {"enabled": False, "message": worldlabs_needs_blender()} if premium_active(): return premium_integration_status("worldlabs", enabled) if not enabled: return { "enabled": False, "message": """World Labs integration is currently disabled. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Under Gaussian Worlds, check World Labs 3. Choose a model and fill in the API Key (from platform.worldlabs.ai)""", } if not self._get_worldlabs_api_key(): return { "enabled": False, "message": """World Labs integration is currently enabled, but the API key is not given. To enable it: 1. In the 3D Viewport, find the MCP for Blender panel in the sidebar (press N if hidden) 2. Under Gaussian Worlds, keep World Labs checked 3. Fill in the API Key (from platform.worldlabs.ai)""", } model, error = self._resolve_worldlabs_model() if error: return {"enabled": False, "message": error["error"]} choices = ", ".join(f"{label} ({ident})" for ident, label in WORLDLABS_MODELS.items()) return { "enabled": True, "model": model, "message": ( f"World Labs integration is enabled and ready to use. Model: {WORLDLABS_MODELS[model]}. " f"Sidebar choices: {choices}." ), } def _worldlabs_request(self, method, path, body=None): """(payload, None) on success, else (None, {"error": readable message}). Messages come from fixed text or World Labs' reply, never the request, so the key can't leak into them.""" api_key = self._get_worldlabs_api_key() if not api_key: return None, {"error": "World Labs API key is not given"} headers = {**WORLDLABS_HEADERS, "WLT-Api-Key": api_key} try: response = requests.request(method, f"{WORLDLABS_API_BASE}{path}", headers=headers, json=body, timeout=WORLDLABS_TIMEOUT) except Exception: return None, {"error": "World Labs request failed. Check the internet connection and try again"} try: payload = response.json() except Exception: payload = None if response.ok and isinstance(payload, dict): return payload, None if response.status_code == 401: return None, {"error": "World Labs rejected the API key"} if response.status_code == 404: return None, {"error": "World Labs has no such generation; it may have expired"} fallback = { 402: ("Out of World Labs API credits. Add some at platform.worldlabs.ai/billing " "(Marble app credits don't count)"), 429: "World Labs rate limit hit, wait a minute and retry", }.get(response.status_code, f"World Labs request failed with status {response.status_code}") detail = payload.get("detail") if isinstance(payload, dict) else None return None, {"error": detail if isinstance(detail, str) and detail else fallback} def create_worldlabs_job(self, text_prompt=None, image=None, name=None, **_unused): """Start a World Labs world from text, an image or a folder of images, with the sidebar's model.""" if not worldlabs_supported(): return {"error": worldlabs_needs_blender()} text_prompt = (text_prompt or "").strip() image = (image or "").strip() if bool(text_prompt) == bool(image): return {"error": "Provide either a text prompt or an image, not both"} model, _error = self._resolve_worldlabs_model() try: world_prompt = worldlabs_world_prompt(text_prompt, image) except (OSError, ValueError) as e: return {"error": str(e)} body = {"model": model, "world_prompt": world_prompt} if name: body["display_name"] = str(name)[:64] data, error = self._worldlabs_request("POST", "/worlds:generate", body) if error: return error if not data.get("operation_id"): return {"error": "World Labs response did not include an operation id"} return {"job_id": data["operation_id"], "kind": "op", "model": model} def _worldlabs_operation(self, job_id): return self._worldlabs_request("GET", f"/operations/{quote(str(job_id), safe='')}") def poll_worldlabs_job(self, job_id=None, kind=None): """Query one World Labs generation. Does not wait; the MCP client polls again.""" if not job_id: return {"error": "job_id is required"} if kind == "prm": return {"error": "This World Labs generation was started through Premium. Switch Generation Source " "back to Premium in the add-on preferences to finish it."} data, error = self._worldlabs_operation(job_id) if error: return error return worldlabs_operation_status(data) def import_worldlabs_world(self, name, job_id=None, kind=None, resolution="500k"): """Download a finished World Labs world and build it in the scene.""" if not job_id: return {"succeed": False, "error": "job_id is required"} data, error = self._worldlabs_operation(job_id) if error: return {"succeed": False, **error} world = data.get("response") if data.get("done") and not data.get("error") else None if not isinstance(world, dict): return {"succeed": False, "error": "The world isn't finished yet. Poll until SUCCEEDED, then import."} assets = world.get("assets") or {} splats = assets.get("splats") or {} urls = splats.get("spz_urls") or {} resolution = resolution if resolution in WORLDLABS_RESOLUTIONS else "500k" url = urls.get(resolution) or urls.get("500k") or next((u for u in urls.values() if u), None) if not url: return {"succeed": False, "error": "World Labs returned no splat file for this world"} if not urls.get(resolution): resolution = next(res for res, u in urls.items() if u == url) result = import_world_assets( name, url, resolution, splats.get("semantics_metadata"), (assets.get("mesh") or {}).get("collider_mesh_url"), (assets.get("imagery") or {}).get("pano_url"), ) if result.get("succeed") and world.get("model"): result["model"] = WORLDLABS_MODELS.get(world["model"], world["model"]) return result #endregion #region Premium # Premium is a different key, not a different set of tools. With the Premium # toggle on, the Hyper3D, Hunyuan3D and Meshy commands send the same request through # the MCP for Blender server, which holds the fal and Meshy keys and decides quotas, and # replies are reshaped into the fal/Tencent/Meshy shapes the MCP tools already # parse. With generation_source left at # BYOK nothing here runs, and nothing here touches the network until the user # activates a key. # --- importing a finished job's files # Files keep their own names, because an OBJ finds its MTL and the MTL finds # its texture by name. MODEL_DOWNLOAD_TIMEOUT = 120 def _safe_file_name(name, fallback): name = re.sub(r"[^A-Za-z0-9._-]", "_", osp.basename(str(name or ""))) return name if name.strip(".") else fallback def _match_texture_names(directory): """If a texture arrived without its file name, save it under the one name the MTL is still missing.""" names = os.listdir(directory) referenced = set() for name in names: if name.lower().endswith(".mtl"): with open(osp.join(directory, name), encoding="utf-8", errors="replace") as f: for line in f: parts = line.split() if len(parts) >= 2 and (parts[0].lower().startswith("map_") or parts[0].lower() == "bump"): referenced.add(osp.basename(parts[-1].replace("\\", "/"))) missing = [name for name in referenced if name not in names] spare = [name for name in names if name.lower().endswith((".png", ".jpg", ".jpeg")) and name not in referenced] if len(missing) == 1 and len(spare) == 1 and _safe_file_name(missing[0], "") == missing[0]: shutil.copyfile(osp.join(directory, spare[0]), osp.join(directory, missing[0])) def _download_model_files(files, directory): """files: [{role, format, url, file_name}]. Returns (model path, format).""" model = None used = set() for index, file in enumerate(files): url = str(file.get("url") or "") if not re.match(r"^https?://", url, re.IGNORECASE): raise ValueError("Invalid model file URL.") fmt = str(file.get("format") or "").lower() name = _safe_file_name(file.get("file_name"), f"{file.get('role') or 'file'}.{fmt or 'bin'}") if name in used: name = f"{index}_{name}" used.add(name) path = osp.join(directory, name) response = requests.get(url, stream=True, timeout=MODEL_DOWNLOAD_TIMEOUT) response.raise_for_status() with open(path, "wb") as f: for chunk in response.iter_content(chunk_size=8192): f.write(chunk) if file.get("role") == "model" and model is None: model = (path, fmt or osp.splitext(name)[1].lstrip(".").lower()) if model is None: raise ValueError("No model file to import.") _match_texture_names(directory) return model def _import_mesh_file(path, fmt, name): existing_objects = set(bpy.data.objects) existing_images = set(bpy.data.images) if fmt == "obj": if bpy.app.version >= (4, 0, 0): bpy.ops.wm.obj_import(filepath=path) else: bpy.ops.import_scene.obj(filepath=path) else: bpy.ops.import_scene.gltf(filepath=path) # The download folder is deleted after import, so embed any texture the # OBJ importer loaded from it. glTF textures are packed already. for image in set(bpy.data.images) - existing_images: with suppress(Exception): if image.filepath and not image.packed_file: image.pack() imported = set(bpy.data.objects) - existing_objects meshes = [obj for obj in imported if obj.type == "MESH"] if not meshes: raise ValueError("No mesh objects were imported.") obj = max(meshes, key=lambda o: len(o.data.vertices)) # glTF wraps the mesh in an empty; drop it so the mesh is the object Claude moves. parent = obj.parent if parent is not None and parent in imported and parent.type == "EMPTY" and len(parent.children) == 1: matrix = obj.matrix_world.copy() obj.parent = None obj.matrix_world = matrix bpy.data.objects.remove(parent) if name: obj.name = name with suppress(Exception): obj.data.name = name return obj def import_model_files(files, name): """Download and import; returns the importers' usual reply shape.""" temp_dir = tempfile.mkdtemp(prefix="blendermcp_model_") try: path, fmt = _download_model_files(files, temp_dir) obj = _import_mesh_file(path, fmt, name) return { "succeed": True, "name": obj.name, "type": obj.type, "location": [obj.location.x, obj.location.y, obj.location.z], "rotation": [obj.rotation_euler.x, obj.rotation_euler.y, obj.rotation_euler.z], "scale": [obj.scale.x, obj.scale.y, obj.scale.z], "world_bounding_box": BlenderMCPServer._get_aabb(obj), } except Exception as e: return {"succeed": False, "error": str(e)} finally: with suppress(Exception): shutil.rmtree(temp_dir) # --- World Labs worlds, on either key def worldlabs_supported(): """Blender imports Gaussian splats from SPZ files from 5.3 on.""" return (bpy.app.version >= WORLDLABS_MIN_BLENDER and bool(getattr(bpy.app.build_options, "io_spz", False))) def worldlabs_needs_blender(): return ("World Labs worlds need Blender 5.3 or newer, which imports Gaussian splats; this is Blender " f"{bpy.app.version_string}.") def _image_extension(data): if data.startswith(b"\x89PNG"): return "png" if data[:4] == b"RIFF": return "webp" return "jpg" def _worldlabs_content(image): """One image as World Labs content: a URL as given, since World Labs fetches it itself, or a local file inline.""" if re.match(r"^https?://", image, re.IGNORECASE): return {"source": "uri", "uri": image} if not osp.isfile(image): raise ValueError(f"Image file not found: {image}") if osp.getsize(image) > WORLDLABS_IMAGE_MAX_BYTES: raise ValueError(f"World Labs takes local images up to 10 MB; {image} is larger. " "Use a smaller image or an image URL.") data = _read_image_file(image) return {"source": "data_base64", "data_base64": base64.b64encode(data).decode("ascii"), "extension": _image_extension(data)} def worldlabs_world_prompt(text_prompt, image): """The world_prompt for text, one image (a panorama is detected), or a folder of up to 4 views spread evenly around the place, first at the front.""" if text_prompt: return {"type": "text", "text_prompt": text_prompt} if not osp.isdir(image): return {"type": "image", "image_prompt": _worldlabs_content(image)} paths = sorted(osp.join(image, name) for name in os.listdir(image) if osp.isfile(osp.join(image, name)) and name.lower().endswith(WORLDLABS_IMAGE_SUFFIXES)) if not paths: raise ValueError(f"No PNG, JPEG or WebP images in {image}.") if len(paths) > WORLDLABS_MAX_IMAGES: raise ValueError(f"World Labs takes up to {WORLDLABS_MAX_IMAGES} images; {image} has {len(paths)}.") return {"type": "multi-image", "multi_image_prompt": [ {"azimuth": round(index * 360 / len(paths)), "content": _worldlabs_content(path)} for index, path in enumerate(paths) ]} def worldlabs_operation_status(operation): """A World Labs operation as {status, progress | error}.""" if operation.get("done"): error = operation.get("error") if error: message = error.get("message") if isinstance(error, dict) else error return {"status": "FAILED", "error": str(message or "World generation failed")} return {"status": "SUCCEEDED"} progress = (operation.get("metadata") or {}).get("progress") or {} return {"status": "IN_PROGRESS", "progress": progress.get("description") or progress.get("status")} def _download_world_file(url, directory, file_name): if not re.match(r"^https?://", str(url or ""), re.IGNORECASE): raise ValueError("Invalid world file URL.") path = osp.join(directory, file_name) response = requests.get(url, headers=WORLDLABS_HEADERS, stream=True, timeout=MODEL_DOWNLOAD_TIMEOUT) response.raise_for_status() with open(path, "wb") as f: for chunk in response.iter_content(chunk_size=65536): f.write(chunk) return path def _set_world_panorama(path, name): """Make the panorama the background of a new world, leaving the scene's old world in the file. Marble's panorama is centred on the generation viewpoint's forward direction, which is +Y once the world is upright; an environment image's centre faces +X, hence the turn about Z.""" image = bpy.data.images.load(path) image.pack() world = bpy.data.worlds.new(f"{name} Sky") with suppress(Exception): world.use_nodes = True tree = world.node_tree if tree is None: raise ValueError("this Blender gave the new world no node tree") nodes = tree.nodes background = next((n for n in nodes if n.type == "BACKGROUND"), None) or nodes.new("ShaderNodeBackground") output = next((n for n in nodes if n.type == "OUTPUT_WORLD"), None) or nodes.new("ShaderNodeOutputWorld") coords = nodes.new("ShaderNodeTexCoord") mapping = nodes.new("ShaderNodeMapping") environment = nodes.new("ShaderNodeTexEnvironment") environment.image = image mapping.inputs["Rotation"].default_value = (0.0, 0.0, -math.pi / 2) tree.links.new(coords.outputs["Generated"], mapping.inputs["Vector"]) tree.links.new(mapping.outputs["Vector"], environment.inputs["Vector"]) tree.links.new(environment.outputs["Color"], background.inputs["Color"]) tree.links.new(background.outputs["Background"], output.inputs["Surface"]) bpy.context.scene.world = world return world.name def _world_float(value, default): try: number = float(value) except (TypeError, ValueError): return default return number if math.isfinite(number) else default def import_world_assets(name, splats_url, resolution, semantics=None, collider_url=None, pano_url=None): """Build a World Labs world in the scene: an empty named `name` parenting the splats and a hidden collision mesh, with the panorama as a new world background. Marble files are in raw OpenCV axes (x right, y down, z forward), and Blender's SPZ and glTF importers both read them as Y-up, so each part turns 180 degrees about X as well. World Labs' scale factor and ground offset then put it in metres with the ground at z=0 and the generation viewpoint at (0, 0, offset).""" if not worldlabs_supported(): return {"succeed": False, "error": worldlabs_needs_blender()} semantics = semantics if isinstance(semantics, dict) else {} scale = _world_float(semantics.get("metric_scale_factor"), 1.0) scale = scale if scale > 0 else 1.0 ground = _world_float(semantics.get("ground_plane_offset"), 0.0) upright = (mathutils.Matrix.Translation((0.0, 0.0, ground)) @ mathutils.Matrix.Rotation(math.pi, 4, "X") @ mathutils.Matrix.Scale(scale, 4)) notes = [] temp_dir = tempfile.mkdtemp(prefix="blendermcp_world_") try: splats_path = _download_world_file(splats_url, temp_dir, "splats.spz") existing = set(bpy.data.objects) try: bpy.ops.wm.spz_import(filepath=splats_path) except RuntimeError: # The importer needs an active window, which a timer may not have. windows = bpy.context.window_manager.windows if not windows: raise with bpy.context.temp_override(window=windows[0]): bpy.ops.wm.spz_import(filepath=splats_path) imported = [obj for obj in set(bpy.data.objects) - existing if obj.type == "POINTCLOUD"] if not imported: raise ValueError("Blender imported no splats from the SPZ file") splats = imported[0] splats.name = f"{name} Splats" with suppress(Exception): splats.data.name = splats.name root = bpy.data.objects.new(name, None) root.empty_display_type = "PLAIN_AXES" for collection in splats.users_collection: collection.objects.link(root) break else: bpy.context.scene.collection.objects.link(root) def place(obj): basis = obj.matrix_basis.copy() obj.parent = root obj.matrix_parent_inverse.identity() obj.matrix_basis = upright @ basis place(splats) collider = None if collider_url: try: collider = _import_mesh_file(_download_world_file(collider_url, temp_dir, "collider.glb"), "glb", f"{name} Collider") place(collider) collider.display_type = "WIRE" collider.hide_render = True collider.hide_set(True) except Exception as e: notes.append(f"The collision mesh couldn't be imported ({e}).") background = None if pano_url: try: background = _set_world_panorama(_download_world_file(pano_url, temp_dir, "panorama"), name) except Exception as e: notes.append(f"The panorama couldn't be set as the background ({e}).") bpy.context.view_layer.update() result = { "succeed": True, "name": root.name, "splats": splats.name, "collider": collider.name if collider else None, "background": background, "resolution": resolution, "metric": abs(scale - 1.0) > 1e-6, "viewpoint": [0.0, 0.0, round(ground, 3)], "notes": notes, } if collider: result["world_bounding_box"] = BlenderMCPServer._get_aabb(collider) return result except Exception as e: return {"succeed": False, "error": f"Failed to import the World Labs world: {e}"} finally: with suppress(Exception): shutil.rmtree(temp_dir) # Overridden by BLENDERMCP_PREMIUM_API_URL, so forks can point at their own # Supabase project without editing code. PREMIUM_API_URL_DEFAULT = "https://dbunjhuejdwwcafedslw.supabase.co/functions/v1/premium" # Links to it add ?ref= saying where the user clicked, for the site's analytics. PREMIUM_PRICING_URL = "https://mcp-for-blender.com/premium" PREMIUM_MANAGE_URL_DEFAULT = "https://mcp-for-blender.com/account" PREMIUM_TIMEOUT = 30 PREMIUM_MAX_IMAGE_BYTES = 8 * 1024 * 1024 # fal's image-to-3D input limit # Fallback wording for codes the addon raises itself or that arrive without a # message. The server's message wins when it sends one. PREMIUM_ERROR_MESSAGES = { "INVALID_KEY": "License key not recognised. Check it in Preferences, or switch to your own API keys.", "NOT_ACTIVATED": "This device isn't activated. Click Activate in Preferences.", "ACTIVATION_LIMIT": "Key is active on 3 devices. Deactivate one from its Blender Preferences.", "NO_ACTIVE_SUBSCRIPTION": "Your Premium subscription isn't active. Manage it at the account link.", "NOT_IN_PLAN": "High-quality models are included in Pro. Use standard quality, or upgrade.", "QUOTA_EXHAUSTED": "You've used all generations this month. Upgrade for more.", "TOO_MANY_IN_FLIGHT": "Wait for the current generation to finish, then try again.", "SERVICE_PAUSED": "Premium generation is paused briefly. Your own API keys still work.", "PROVIDER_ERROR": "The model provider failed. This attempt wasn't counted; try again.", "ADDON_OUTDATED": "Update the addon to keep using Premium.", "NETWORK_ERROR": "Couldn't reach the Premium server. Your own API keys still work.", "BAD_RESPONSE": "The Premium server sent an unexpected reply. Try again shortly.", } # The scene checkboxes that turn each generator on, in both modes. PREMIUM_INTEGRATIONS = { "meshy": ("Meshy", "blendermcp_use_meshy"), "hyper3d": ("Hyper3D Rodin", "blendermcp_use_hyper3d"), "hunyuan3d": ("Hunyuan3D", "blendermcp_use_hunyuan3d"), "tripo": ("Tripo", "blendermcp_use_tripo"), "worldlabs": ("World Labs", "blendermcp_use_worldlabs"), } # Last usage summary the server sent. draw() reads only this, never the network. _premium_status = {} # Hunyuan's import tool takes a URL, but an OBJ result is three files, so # remember each finished job's full file list by its model URL. _premium_files_by_url = {} def _premium_prefs(): try: return get_blendermcp_addon_preferences() except Exception: return None def _premium_setting(pref_attr, env_var): prefs = _premium_prefs() value = getattr(prefs, pref_attr, "") if prefs else "" return value or os.getenv(env_var, "") def premium_license_key(): return _premium_setting("premium_license_key", "BLENDERMCP_PREMIUM_LICENSE_KEY").strip() def premium_instance_id(): return _premium_setting("premium_instance_id", "BLENDERMCP_PREMIUM_INSTANCE_ID").strip() def premium_api_url(): return (os.getenv("BLENDERMCP_PREMIUM_API_URL") or PREMIUM_API_URL_DEFAULT).rstrip("/") def premium_active(): """Premium replaces the user's own keys when selected in Preferences, or for headless runs that supply a license key by env var.""" prefs = _premium_prefs() if prefs is not None and getattr(prefs, "generation_source", "BYOK") == "PREMIUM": return True return bool(os.getenv("BLENDERMCP_PREMIUM_LICENSE_KEY")) def premium_enabled_generators(): """Generators the user can call through Premium right now, for the handshake. Reads local settings only, never the network.""" try: if not premium_active(): return [] scene = bpy.context.scene return [name for name, (_label, prop) in PREMIUM_INTEGRATIONS.items() if getattr(scene, prop, False) and (name != "worldlabs" or worldlabs_supported())] except Exception: return [] def premium_error(code, message=None): message = message or PREMIUM_ERROR_MESSAGES.get(code, code) return {"error": message, "code": code, "message": message} def _premium_tag_redraw(): try: for window in bpy.context.window_manager.windows: for area in window.screen.areas: if area.type in {"VIEW_3D", "PREFERENCES"}: area.tag_redraw() except Exception: pass def _premium_remember_usage(data): usage = data.get("usage") if isinstance(data, dict) else None if isinstance(usage, dict): _premium_status.clear() _premium_status.update(usage) _premium_tag_redraw() def premium_request(method, path, payload=None, auth=True): """Send one request to the Premium server. Never raises: transport failures and non-JSON replies come back as {error, code, message}.""" headers = { "X-Addon-Version": ".".join(str(part) for part in bl_info["version"]), "X-Addon-Protocol": str(ADDON_PROTOCOL_VERSION), } if auth: key = premium_license_key() if not key: return premium_error("INVALID_KEY", "No Premium license key set. Paste it in Preferences, or switch to your own API keys.") instance_id = premium_instance_id() if not instance_id: return premium_error("NOT_ACTIVATED") headers["Authorization"] = f"Bearer {key}" headers["X-Instance-Id"] = instance_id try: response = requests.request( method, premium_api_url() + path, headers=headers, json=payload, timeout=PREMIUM_TIMEOUT, ) except Exception as e: return premium_error("NETWORK_ERROR", f"{PREMIUM_ERROR_MESSAGES['NETWORK_ERROR']} ({e})") try: data = response.json() except Exception: data = None if not isinstance(data, dict): return premium_error("BAD_RESPONSE", f"{PREMIUM_ERROR_MESSAGES['BAD_RESPONSE']} (HTTP {response.status_code})") _premium_remember_usage(data) if response.status_code >= 400 or data.get("code"): code = data.get("code") or "BAD_RESPONSE" return premium_error(code, data.get("message")) return data def _premium_format_date(value): try: moment = datetime.fromisoformat(str(value).replace("Z", "+00:00")) except (TypeError, ValueError): return None return f"{moment.strftime('%b')} {moment.day}" def _premium_remaining(status, pool): counts = status.get(pool) or {} return int(counts.get("remaining", max(0, counts.get("total", 0) - counts.get("used", 0)))) def premium_short_status(): """One line for the sidebar, from the cache only. The cache is empty after a restart until the next request, which isn't the same as no plan.""" if not premium_instance_id(): return "Premium: not activated" if not _premium_status: return "Premium: activated" if not _premium_status.get("tier"): return "Premium: subscription not active" return (f"Premium: {str(_premium_status['tier']).title()}, " f"{_premium_remaining(_premium_status, 'standard')} + " f"{_premium_remaining(_premium_status, 'premium')} left") def premium_summary(status=None): status = _premium_status if status is None else status tier = status.get("tier") if not tier: return "Premium: no active subscription." text = (f"Premium ({str(tier).title()}): {_premium_remaining(status, 'standard')} standard and " f"{_premium_remaining(status, 'premium')} high-quality generations left") reset = _premium_format_date(status.get("resets_at")) return f"{text}, resets {reset}" if reset else text def _premium_high_locked(): """True once the server has said this plan has no high-quality allowance.""" return bool(_premium_status.get("tier")) and (_premium_status.get("premium") or {}).get("total", 0) == 0 def premium_default_quality(): prefs = _premium_prefs() value = getattr(prefs, "premium_default_quality", "standard") if prefs else "standard" if value not in ("standard", "high") or (value == "high" and _premium_high_locked()): return "standard" return value def _premium_quality(model, quality, from_image): """An explicit quality wins. Otherwise Rodin, and Tripo from an image, use high (their only option), and everything else the user's default.""" if quality: return quality if model == "rodin" or (model == "tripo" and from_image): return "high" return premium_default_quality() def premium_integration_status(integration, enabled): """Reply for get_hyper3d_status / get_hunyuan3d_status / get_tripo_status / get_meshy_status / get_worldlabs_status.""" label, prop = PREMIUM_INTEGRATIONS[integration] if not enabled: return {"enabled": False, "mode": "PREMIUM", "message": ( f"{label} is turned off. To use it through Premium, check '{label}' in the MCP for Blender " "sidebar (press N in the 3D Viewport).")} result = premium_request("GET", "/status") if result.get("code") in {"NETWORK_ERROR", "BAD_RESPONSE"} and _premium_status.get("tier"): summary = premium_summary() + " (cached; the Premium server is unreachable right now)" elif result.get("code"): return {"enabled": False, "mode": "PREMIUM", "message": result["message"]} else: summary = premium_summary() quality = (f"Default quality: {premium_default_quality()}. Pass quality='high' only when the user asks " "for more detail; it uses a high-quality generation.") flow = { "hyper3d": ("Mode: PREMIUM. Behaves like FAL_AI mode: pass request_id to poll_rodin_job_status and " "import_generated_asset. Every Rodin generation counts as high-quality."), "hunyuan3d": ("Mode: PREMIUM. Follow the OFFICIAL_API flow: generate_hunyuan3d_model, then " "poll_hunyuan_job_status, then import_generated_asset_hunyuan with the ResultFile3Ds URL. " + quality), "tripo": "Mode: PREMIUM. From an image, Tripo is high-quality only. " + quality, "meshy": ("Mode: PREMIUM. Meshy uses its latest model and every generation counts as standard " "quality. Models arrive at real-world size with their origin at the bottom."), "worldlabs": ("Mode: PREMIUM. Every world is Marble 1.1 and uses a high-quality generation (Pro and " "up). One image or a text prompt per world."), }[integration] return {"enabled": True, "mode": "PREMIUM", "message": f"{summary}. {flow}"} IMAGE_FETCH_MAX_REDIRECTS = 3 def _is_image_bytes(data): """PNG, JPEG or WebP, by their magic numbers rather than the file name.""" return (data.startswith(b"\x89PNG\r\n\x1a\n") or data.startswith(b"\xff\xd8\xff") or (data[:4] == b"RIFF" and data[8:12] == b"WEBP")) def _read_image_file(path): """A local image's bytes. They go to a generation service, so a path to anything but an image (a key file, a config) raises ValueError.""" with open(path, "rb") as f: data = f.read() if not _is_image_bytes(data): raise ValueError(f"Not a PNG, JPEG or WebP image: {path}") return data def _check_public_url(url): """Raise ValueError unless every address the URL's host resolves to is public.""" parsed = urlparse(url) if parsed.scheme.lower() not in ("http", "https") or not parsed.hostname: raise ValueError(f"Not an http(s) URL: {url}") try: infos = socket.getaddrinfo(parsed.hostname, parsed.port, proto=socket.IPPROTO_TCP) except (socket.gaierror, ValueError) as e: raise ValueError(f"Can't resolve {parsed.hostname}: {e}") for info in infos: address = ipaddress.ip_address(info[4][0].split("%")[0]) if address.version == 6 and address.ipv4_mapped: address = address.ipv4_mapped if not address.is_global: raise ValueError(f"{parsed.hostname} is a local or private address. " "Give a public image URL or a local file path instead.") def _fetch_public_image(url): """Download an image named by URL. Local and private hosts are refused at every redirect, so a URL can't reach into the user's own network.""" for _ in range(IMAGE_FETCH_MAX_REDIRECTS + 1): _check_public_url(url) response = requests.get(url, timeout=30, allow_redirects=False) location = response.headers.get("Location") if 300 <= response.status_code < 400 and location: url = urljoin(url, location) continue response.raise_for_status() if not _is_image_bytes(response.content): raise ValueError(f"Not a PNG, JPEG or WebP image: {url}") return response.content raise ValueError("Too many redirects fetching the image") def _premium_image_payload(image): """URLs go to the server as-is; local files are read here, since the server cannot see the user's disk.""" if isinstance(image, (tuple, list)) and len(image) == 2: suffix, encoded = image raw = base64.b64decode(encoded) if isinstance(encoded, str) else encoded return {"image_base64": base64.b64encode(raw).decode("ascii"), "image_mime": _premium_mime(suffix)}, len(raw) if re.match(r'^https?://', str(image), re.IGNORECASE): return {"image_url": image}, 0 raw = _read_image_file(image) return {"image_base64": base64.b64encode(raw).decode("ascii"), "image_mime": _premium_mime(osp.splitext(image)[1])}, len(raw) def _premium_mime(suffix): suffix = str(suffix or "").lower().lstrip(".") return {"jpg": "image/jpeg", "jpeg": "image/jpeg", "webp": "image/webp"}.get(suffix, "image/png") def premium_create_job(model, quality="standard", text_prompt=None, image=None, bbox_condition=None): if bool(text_prompt) == bool(image): return {"error": "Give exactly one of a text prompt or an image."} if text_prompt and len(text_prompt) > 1024: return {"error": "Prompt exceeds 1024 characters limit"} if quality not in ("standard", "high"): return {"error": "quality must be 'standard' or 'high'"} payload = {"client_request_id": str(uuid.uuid4()), "operation": "generate", "model": model, "quality": quality} if text_prompt: payload["prompt"] = text_prompt else: try: image_fields, size = _premium_image_payload(image) except Exception as e: return {"error": f"Image encoding failed: {e}"} if size > PREMIUM_MAX_IMAGE_BYTES: return {"error": "Image is larger than 8 MB; use a smaller image or an image URL."} payload.update(image_fields) if bbox_condition: payload["bbox_condition"] = bbox_condition result = premium_request("POST", "/jobs", payload) if result.get("code") == "NETWORK_ERROR": # The first attempt may have reached the server; the same # client_request_id returns that job instead of charging again. result = premium_request("POST", "/jobs", payload) return result def _premium_job(job_id): return premium_request("GET", f"/jobs/{quote(str(job_id), safe='')}") def _premium_job_files(job): files = job.get("files") if not files and job.get("result_url"): # Jobs finished before the server sent file lists were always one GLB. files = [{"role": "model", "format": "glb", "url": job["result_url"], "file_name": "model.glb"}] return files or None def premium_import_job(request_id, name): if not request_id: return {"succeed": False, "error": "request_id is required"} job = _premium_job(request_id) if job.get("code"): return {"succeed": False, **job} files = _premium_job_files(job) if job.get("status") != "succeeded" or not files: return {"succeed": False, "error": "Generation isn't finished yet. Poll until COMPLETED, then import."} return import_model_files(files, name) # Rodin and Tripo: fal-style shapes, so the tools treat Premium like fal mode. _PREMIUM_FAL_STATUS = {"reserved": "IN_QUEUE", "succeeded": "COMPLETED", "failed": "FAILED"} def premium_poll_fal_job(request_id): if not request_id: return {"error": "request_id is required"} job = _premium_job(request_id) if job.get("code") or "status" not in job: return job status = _PREMIUM_FAL_STATUS.get(job["status"]) if status is None: status = "IN_QUEUE" if job.get("provider_status") == "IN_QUEUE" else "IN_PROGRESS" reply = {"status": status} if status == "FAILED": reply["error"] = (job.get("error") or "Generation failed") + ". This attempt wasn't counted." return reply def _premium_fal_reply(result, note=None): if not result.get("job_id"): return result reply = {"request_id": result["job_id"], "status": "IN_QUEUE", "message": premium_summary()} if note: reply["note"] = note return reply def premium_create_rodin_job(text_prompt=None, images=None, bbox_condition=None): image = images[0] if images else None result = premium_create_job("rodin", "high", text_prompt=text_prompt, image=image, bbox_condition=bbox_condition) return _premium_fal_reply(result, "Premium uses the first image only." if images and len(images) > 1 else None) def premium_create_tripo_job(text_prompt=None, image=None, quality=None): quality = _premium_quality("tripo", quality, bool(image)) return _premium_fal_reply(premium_create_job("tripo", quality, text_prompt=text_prompt, image=image)) def premium_tripo_handlers(): """Tripo commands, registered in Premium mode when its checkbox is on.""" if not (premium_active() and getattr(bpy.context.scene, "blendermcp_use_tripo", False)): return {} return { "create_tripo_job": premium_create_tripo_job, "poll_tripo_job_status": premium_poll_fal_job, "import_generated_asset_tripo": premium_import_job, } # Meshy: Meshy-style shapes. The Premium server runs a text job's preview and # refine as one job, so there's no refine step here, and "prm" tells these # jobs apart from tasks started on the user's own key. _PREMIUM_MESHY_STATUS = {"reserved": "PENDING", "running": "IN_PROGRESS", "succeeded": "SUCCEEDED", "failed": "FAILED"} def premium_create_meshy_job(text_prompt=None, image=None, pose_mode=None): if pose_mode: return {"error": "pose_mode isn't available through Premium yet, only on your own Meshy API key"} result = premium_create_job("meshy", "standard", text_prompt=text_prompt, image=image) if not result.get("job_id"): return result return {"task_id": result["job_id"], "kind": "prm", "message": premium_summary()} def premium_poll_meshy_job(task_id=None, kind=None): if not task_id: return {"error": "task_id is required"} if kind != "prm": return {"error": "This Meshy generation was started with your own Meshy API key. Switch Generation " "Source back to Your own API keys in the add-on preferences to finish it."} job = _premium_job(task_id) if job.get("code") or "status" not in job: return job reply = {"status": _PREMIUM_MESHY_STATUS.get(job["status"], "IN_PROGRESS")} if job.get("progress") is not None: reply["progress"] = job["progress"] if job["status"] == "failed": reply["error"] = (job.get("error") or "Generation failed") + ". This attempt wasn't counted." return reply def premium_import_meshy(name, task_id=None, model_url=None): return premium_import_job(task_id, name) def premium_meshy_handlers(): """Meshy commands in Premium mode; the caller checks the checkbox.""" return { "create_meshy_job": premium_create_meshy_job, "poll_meshy_job_status": premium_poll_meshy_job, "import_generated_asset_meshy": premium_import_meshy, } # World Labs: the same {status, progress | error} replies as on the user's own # key. The Premium server lists the world's files, each splat file with the # world's scale metadata, and "prm" tells these jobs apart. _PREMIUM_WORLD_STATUS = {"succeeded": "SUCCEEDED", "failed": "FAILED"} def premium_create_worldlabs_job(text_prompt=None, image=None, name=None, **_unused): if not worldlabs_supported(): return {"error": worldlabs_needs_blender()} if _premium_high_locked(): return premium_error("NOT_IN_PLAN", "Gaussian worlds use high-quality generations, which are included in " "Premium Pro and up. Upgrade, or use your own World Labs API key.") if image and osp.isdir(str(image)): return {"error": "Through Premium, World Labs takes one image, not a folder. Pass one image, or use " "your own World Labs API key for several views."} result = premium_create_job("worldlabs", "high", text_prompt=text_prompt, image=image) if not result.get("job_id"): return result return {"job_id": result["job_id"], "kind": "prm", "message": premium_summary()} def premium_poll_worldlabs_job(job_id=None, kind=None): if not job_id: return {"error": "job_id is required"} if kind != "prm": return {"error": "This World Labs generation was started with your own World Labs API key. Switch " "Generation Source back to Your own API keys in the add-on preferences to finish it."} job = _premium_job(job_id) if job.get("code") or "status" not in job: return job reply = {"status": _PREMIUM_WORLD_STATUS.get(job["status"], "IN_PROGRESS")} if job["status"] == "failed": reply["error"] = (job.get("error") or "Generation failed") + ". This attempt wasn't counted." elif job.get("provider_status"): reply["progress"] = job["provider_status"] return reply def premium_import_worldlabs(name, job_id=None, kind=None, resolution="500k"): if not job_id: return {"succeed": False, "error": "job_id is required"} job = _premium_job(job_id) if job.get("code"): return {"succeed": False, **job} files = job.get("files") or [] if job.get("status") != "succeeded" or not files: return {"succeed": False, "error": "The world isn't finished yet. Poll until SUCCEEDED, then import."} splats = [f for f in files if isinstance(f, dict) and f.get("role") == "splats" and f.get("url")] chosen = (next((f for f in splats if f.get("resolution") == resolution), None) or next((f for f in splats if f.get("resolution") == "500k"), None) or (splats[0] if splats else None)) if not chosen: return {"succeed": False, "error": "The Premium server returned no splat file for this world"} collider = next((f.get("url") for f in files if isinstance(f, dict) and f.get("role") == "collider"), None) pano = next((f.get("url") for f in files if isinstance(f, dict) and f.get("role") == "panorama"), None) result = import_world_assets(name, chosen["url"], chosen.get("resolution") or resolution, chosen.get("metadata"), collider, pano) if result.get("succeed"): result["model"] = WORLDLABS_MODELS[WORLDLABS_PREMIUM_MODEL] return result def premium_worldlabs_handlers(): """World Labs commands in Premium mode; the caller checks the checkbox.""" return { "create_worldlabs_job": premium_create_worldlabs_job, "poll_worldlabs_job": premium_poll_worldlabs_job, "import_worldlabs_world": premium_import_worldlabs, } # Hunyuan: Tencent-style shapes, so server.py wraps JobId as job_ and # reads Status / ResultFile3Ds exactly as it does for OFFICIAL_API. _PREMIUM_TENCENT_STATUS = {"reserved": "WAIT", "running": "RUN", "succeeded": "DONE", "failed": "FAIL"} def premium_create_hunyuan_job(text_prompt=None, image=None, quality=None): quality = _premium_quality("hunyuan", quality, bool(image)) result = premium_create_job("hunyuan", quality, text_prompt=text_prompt, image=image) if not result.get("job_id"): return result return {"Response": {"JobId": result["job_id"]}, "message": premium_summary()} def premium_poll_hunyuan_job_status(job_id=None): if not job_id: return {"error": "JobId is required"} job = _premium_job(str(job_id).removeprefix("job_")) if job.get("code") or "status" not in job: return job response = {"Status": _PREMIUM_TENCENT_STATUS.get(job["status"], "RUN")} files = _premium_job_files(job) if job["status"] == "succeeded" else None if files: model = next((f for f in files if f.get("role") == "model"), files[0]) _premium_files_by_url[model["url"]] = files response["ResultFile3Ds"] = [{"Type": str(model.get("format") or "glb").upper(), "Url": model["url"]}] if job["status"] == "failed": response["ErrorMessage"] = (job.get("error") or "Generation failed") + ". This attempt wasn't counted." return {"Response": response} def premium_import_generated_asset_hunyuan(name, zip_file_url): if not zip_file_url or not re.match(r'^https?://', zip_file_url, re.IGNORECASE): return {"error": "Invalid URL format. Must start with http:// or https://"} files = _premium_files_by_url.get(zip_file_url) if not files: # Blender restarted since the poll: import the URL on its own. path = zip_file_url.split("?", 1)[0].split("#", 1)[0].lower() fmt = "obj" if path.endswith(".obj") else "glb" files = [{"role": "model", "format": fmt, "url": zip_file_url, "file_name": f"model.{fmt}"}] return import_model_files(files, name) # --- UI def _premium_draw_quality(prefs, layout, text="Default quality"): row = layout.row(align=True) row.label(text=text) row.prop_enum(prefs, "premium_default_quality", "standard") locked = _premium_high_locked() sub = row.row(align=True) sub.enabled = not locked sub.prop_enum(prefs, "premium_default_quality", "high", text="High (Pro)" if locked else "High") def premium_draw_preferences(prefs, box): col = box.column() col.prop(prefs, "premium_license_key", text="License Key") row = col.row(align=True) if prefs.premium_instance_id: row.operator("blendermcp.premium_deactivate", text="Deactivate", icon='UNLINKED') row.operator("blendermcp.premium_refresh", text="Refresh", icon='FILE_REFRESH') else: row.operator("blendermcp.premium_activate", text="Activate", icon='LINKED') if prefs.premium_instance_id: col.label(text=premium_summary() if _premium_status else "Click Refresh to load your plan.", icon='INFO') _premium_draw_quality(prefs, col) row = col.row(align=True) row.operator("blendermcp.premium_open_account", text="Manage account", icon='URL') row.operator("wm.url_open", text="Get Premium", icon='FUND').url = PREMIUM_PRICING_URL + "?ref=addon-prefs" def premium_draw_upsell(layout): """For own-key users: a single line saying Premium exists and where to get it.""" row = layout.row(align=True) row.label(text="No API keys? Use Premium", icon='FUND') row.operator("wm.url_open", text="Get Premium").url = PREMIUM_PRICING_URL + "?ref=addon-upsell" def premium_draw_panel(layout, prefs): """Sidebar status in Premium mode. Reads the cache only.""" box = layout.box() col = box.column(align=True) col.label(text=premium_short_status(), icon='FUND') if not premium_instance_id(): col.label(text="Activate your license key in Preferences.") row = col.row(align=True) row.operator("screen.userpref_show", text="Open Preferences", icon='PREFERENCES').section = 'ADDONS' row.operator("wm.url_open", text="Get Premium", icon='FUND').url = PREMIUM_PRICING_URL + "?ref=addon-sidebar" elif not _premium_status: col.operator("blendermcp.premium_refresh", text="Load plan", icon='FILE_REFRESH') elif not _premium_status.get("tier"): col.label(text="Your subscription isn't active.") row = col.row(align=True) row.operator("blendermcp.premium_open_account", text="Manage account", icon='URL') row.operator("wm.url_open", text="Get Premium", icon='FUND').url = PREMIUM_PRICING_URL + "?ref=addon-sidebar" elif prefs is not None: # Quality only means something once there's a plan to spend. col.separator() _premium_draw_quality(prefs, col, text="Quality") class BLENDERMCP_OT_PremiumActivate(bpy.types.Operator): bl_idname = "blendermcp.premium_activate" bl_label = "Activate Premium" bl_description = "Activate this device with your Premium license key" def execute(self, context): prefs = get_blendermcp_addon_preferences(context) key = premium_license_key() if not prefs or not key: self.report({'ERROR'}, "Paste your license key first.") return {'CANCELLED'} result = premium_request("POST", "/activate", { "license_key": key, "device_name": socket.gethostname() or "Blender", }, auth=False) if result.get("code") or not result.get("instance_id"): self.report({'ERROR'}, result.get("message") or "Activation failed.") return {'CANCELLED'} prefs.premium_instance_id = result["instance_id"] prefs.generation_source = "PREMIUM" # Premium covers every generator, so switch them all on in this scene. for _label, prop in PREMIUM_INTEGRATIONS.values(): with suppress(Exception): setattr(context.scene, prop, True) _premium_tag_redraw() self.report({'INFO'}, premium_summary()) return {'FINISHED'} class BLENDERMCP_OT_PremiumDeactivate(bpy.types.Operator): bl_idname = "blendermcp.premium_deactivate" bl_label = "Deactivate Premium" bl_description = "Free this device's activation slot so the key can be used on another machine" def execute(self, context): prefs = get_blendermcp_addon_preferences(context) result = premium_request("POST", "/deactivate", {}) # A key the server no longer knows has nothing left to free. if result.get("code") and result["code"] not in {"INVALID_KEY", "NOT_ACTIVATED"}: self.report({'ERROR'}, result["message"]) return {'CANCELLED'} if prefs: prefs.premium_instance_id = "" # Without an activation Premium can't generate, so go back to own keys. # The license key stays filled in, so reactivating is one click. prefs.generation_source = "BYOK" _premium_status.clear() # Deactivate runs from Preferences; the 3D Viewport sidebar won't redraw on its own. _premium_tag_redraw() self.report({'INFO'}, "This device was deactivated. Generation uses your own API keys again.") return {'FINISHED'} class BLENDERMCP_OT_PremiumRefresh(bpy.types.Operator): bl_idname = "blendermcp.premium_refresh" bl_label = "Refresh Premium Status" bl_description = "Fetch your plan and remaining generations" def execute(self, context): result = premium_request("GET", "/status") if result.get("code"): self.report({'ERROR'}, result["message"]) return {'CANCELLED'} self.report({'INFO'}, premium_summary()) return {'FINISHED'} class BLENDERMCP_OT_PremiumOpenAccount(bpy.types.Operator): bl_idname = "blendermcp.premium_open_account" bl_label = "Manage Premium Account" bl_description = "Upgrade, cancel or download invoices" def execute(self, context): # Portal links are per customer and short-lived, so fetch one per click. url = PREMIUM_MANAGE_URL_DEFAULT if premium_instance_id(): url = premium_request("GET", "/status?portal=1").get("manage_url") or url bpy.ops.wm.url_open(url=url) return {'FINISHED'} PREMIUM_CLASSES = ( BLENDERMCP_OT_PremiumActivate, BLENDERMCP_OT_PremiumDeactivate, BLENDERMCP_OT_PremiumRefresh, BLENDERMCP_OT_PremiumOpenAccount, ) #endregion # Blender Addon Preferences class BLENDERMCP_AddonPreferences(bpy.types.AddonPreferences): bl_idname = __name__ bind_address: bpy.props.StringProperty( name="Bind Address", description="Listener address: localhost or an IPv4 address. Applied on next connection", default="localhost", ) allow_remote_connections: BoolProperty( name="Allow Remote Connections", description=( "Allow non-loopback binding on the next connection. Remote clients can execute " "Python without authentication or encryption. Use only on a trusted network " "with firewall restrictions" ), default=False, ) def _on_telemetry_consent_changed(self, context): try: sync_edit_capture_handlers() except Exception as e: print(f"BlenderMCP: could not sync manual edit handlers: {e}") telemetry_consent: BoolProperty( name="Allow Telemetry", description="Opt in to collection of prompts, code snippets, screenshots, and trajectory data to help improve MCP for Blender. Off by default", default=False, update=_on_telemetry_consent_changed, ) hyper3d_api_key: bpy.props.StringProperty( name="Hyper3D API Key", subtype="PASSWORD", description="Persistent Hyper3D API Key", default="" ) sketchfab_api_key: bpy.props.StringProperty( name="Sketchfab API Key", subtype="PASSWORD", description="Persistent Sketchfab API Key", default="" ) polypizza_api_key: bpy.props.StringProperty( name="Poly Pizza API Key", subtype="PASSWORD", description="Persistent Poly Pizza API Key", default="" ) hunyuan3d_secret_id: bpy.props.StringProperty( name="Hunyuan3D SecretId", description="Persistent Hunyuan3D SecretId", default="" ) hunyuan3d_secret_key: bpy.props.StringProperty( name="Hunyuan3D SecretKey", subtype="PASSWORD", description="Persistent Hunyuan3D SecretKey", default="" ) hunyuan3d_api_url: bpy.props.StringProperty( name="Hunyuan3D API URL", description="Persistent Hunyuan3D API URL", default="" ) generation_source: bpy.props.EnumProperty( name="Generation Source", description="Where 3D model generation runs", items=[ ("BYOK", "Your own API keys", "Use your own Hyper3D, fal.ai, Tripo, Meshy, World Labs or Tencent Cloud keys"), ("PREMIUM", "Premium", "Generate through MCP for Blender Premium with one license key"), ], default="BYOK", ) premium_license_key: bpy.props.StringProperty( name="Premium License Key", subtype="PASSWORD", description="License key from your MCP for Blender Premium purchase", default="" ) premium_instance_id: bpy.props.StringProperty( name="Premium Instance ID", description="Set when this device is activated", default="", options={'HIDDEN'}, ) premium_default_quality: bpy.props.EnumProperty( name="Default Quality", description="Quality Claude uses unless you ask for another. High uses a high-quality generation", items=[ ("standard", "Standard", "Uses a standard generation"), ("high", "High", "More detail; uses a high-quality generation (Pro)"), ], default="standard", ) tripo_domain: bpy.props.EnumProperty( name="Tripo Domain", description="Tripo API region; use an API key from the selected domain", items=TRIPO_DOMAINS, default="ai", ) tripo_api_key: bpy.props.StringProperty( name="Tripo API Key", subtype="PASSWORD", description="Persistent Tripo API Key", default="" ) meshy_api_key: bpy.props.StringProperty( name="Meshy API Key", subtype="PASSWORD", description="Persistent Meshy API Key", default="" ) worldlabs_api_key: bpy.props.StringProperty( name="World Labs API Key", subtype="PASSWORD", description="Persistent World Labs API Key", default="" ) def draw(self, context): layout = self.layout layout.label(text="Server Connection:", icon='NETWORK_DRIVE') connection_box = layout.box() connection_box.prop(self, "bind_address") connection_box.prop(self, "allow_remote_connections") if self.allow_remote_connections: warning = connection_box.column() warning.alert = True warning.label(text="Remote clients can run Python.", icon='ERROR') warning.label(text="No authentication or encryption.") warning.label(text="Use a trusted LAN and a firewall.") connection_box.label(text="Disconnect and reconnect to apply changes.", icon='INFO') layout.separator() # Telemetry section layout.label(text="Telemetry & Privacy:", icon='PREFERENCES') box = layout.box() row = box.row() row.prop(self, "telemetry_consent", text="Allow Telemetry") # Info text box.separator() if self.telemetry_consent: box.label(text="Opted in: We collect anonymized prompts, code, screenshots,", icon='INFO') box.label(text="and trajectory data (actions, scene state, feedback).", icon='BLANK1') else: box.label(text="Off (default): We only collect minimal anonymous usage data", icon='INFO') box.label(text="(tool names, success/failure, duration - no prompts or code).", icon='BLANK1') box.separator() box.label(text="Data is not linked to your name or account. Change this anytime.", icon='CHECKMARK') # Terms and Conditions link box.separator() row = box.row() row.operator("blendermcp.open_terms", text="View Terms and Conditions", icon='TEXT') layout.separator() layout.label(text="3D Generation:", icon='SHADERFX') gen_box = layout.box() gen_box.row().prop(self, "generation_source", expand=True) if self.generation_source == "PREMIUM": premium_draw_preferences(self, gen_box) else: col = gen_box.column() premium_draw_upsell(col) col.separator() col.prop(self, "hyper3d_api_key", text="Hyper3D API Key") row = col.row(align=True) row.operator("wm.url_open", text="hyper3d.ai keys", icon='URL').url = "https://hyper3d.ai/" row.operator("wm.url_open", text="fal.ai keys", icon='URL').url = "https://fal.ai/dashboard/keys" col.separator() col.prop(self, "hunyuan3d_secret_id", text="Hunyuan3D SecretId") col.prop(self, "hunyuan3d_secret_key", text="Hunyuan3D SecretKey") col.operator("wm.url_open", text="Tencent Cloud keys", icon='URL').url = \ "https://console.cloud.tencent.com/cam/capi" col.prop(self, "hunyuan3d_api_url", text="Hunyuan3D API URL") col.separator() col.prop(self, "tripo_domain", text="Tripo Domain", translate=False) col.prop(self, "tripo_api_key", text="Tripo API Key") endpoints = tripo_endpoints(context, self) col.operator("wm.url_open", text="Get Tripo API Key", icon='URL').url = endpoints["keys"] col.separator() col.prop(self, "meshy_api_key", text="Meshy API Key") col.operator("wm.url_open", text="meshy.ai keys", icon='URL').url = MESHY_KEY_URL col.separator() col.prop(self, "worldlabs_api_key", text="World Labs API Key") col.operator("wm.url_open", text="World Labs keys", icon='URL').url = WORLDLABS_KEY_URL layout.separator() layout.label(text="Persistent API Credentials:", icon='LOCKED') cred_box = layout.box() cred_box.prop(self, "sketchfab_api_key", text="Sketchfab API Key") cred_box.prop(self, "polypizza_api_key", text="Poly Pizza API Key") # Blender UI Panel class BLENDERMCP_PT_Panel(bpy.types.Panel): bl_label = "MCP for Blender" bl_idname = "BLENDERMCP_PT_Panel" bl_space_type = 'VIEW_3D' bl_region_type = 'UI' bl_category = 'MCP for Blender' def _integration_header(self, layout, scene, prop_name, title, icon): """Draw an integration as a box with a checkbox header row. Returns the box if the integration is enabled (for settings), else None.""" box = layout.box() row = box.row() row.prop(scene, prop_name, text="") row.label(text=title, icon=icon) return box if getattr(scene, prop_name) else None def draw(self, context): layout = self.layout scene = context.scene prefs = get_blendermcp_addon_preferences(context) # Connection box = layout.box() col = box.column() if scene.blendermcp_server_running: server = getattr(bpy.types, "blendermcp_server", None) running_host = getattr(server, "host", "localhost") running_port = getattr(server, "port", scene.blendermcp_port) col.label(text=f"Connected on {running_host}:{running_port}", icon='CHECKMARK') col.operator("blendermcp.stop_server", text="Disconnect", icon='X') else: col.label(text="Not connected", icon='RADIOBUT_OFF') col.prop(scene, "blendermcp_port") col.operator("blendermcp.start_server", text="Connect to MCP server", icon='PLAY') # Asset libraries layout.separator() layout.label(text="Asset Libraries", icon='ASSET_MANAGER') sub = self._integration_header( layout, scene, "blendermcp_use_polyhaven", "Poly Haven", 'WORLD') if sub: col = sub.column(align=True) col.label(text="Free CC0 HDRIs, textures and models") col.operator("wm.url_open", text="polyhaven.com", icon='URL').url = POLYHAVEN_SITE sub = self._integration_header( layout, scene, "blendermcp_use_sketchfab", "Sketchfab", 'MESH_MONKEY') if sub: col = sub.column(align=True) if prefs: col.prop(prefs, "sketchfab_api_key", text="API Key") else: col.prop(scene, "blendermcp_sketchfab_api_key", text="API Key") sub = self._integration_header( layout, scene, "blendermcp_use_polypizza", "Poly Pizza", 'MESH_ICOSPHERE') if sub: col = sub.column(align=True) if prefs: col.prop(prefs, "polypizza_api_key", text="API Key") else: col.prop(scene, "blendermcp_polypizza_api_key", text="API Key") # AI model generation layout.separator() layout.label(text="AI Model Generation", icon='SHADERFX') premium = premium_active() if premium: premium_draw_panel(layout, prefs) else: premium_draw_upsell(layout) sub = self._integration_header( layout, scene, "blendermcp_use_hyper3d", "Hyper3D Rodin", 'MESH_UVSPHERE') if sub and premium: sub.label(text="Runs through Premium") elif sub: col = sub.column(align=True) col.prop(scene, "blendermcp_hyper3d_mode", text="Mode") if prefs: col.prop(prefs, "hyper3d_api_key", text="API Key") else: col.prop(scene, "blendermcp_hyper3d_api_key", text="API Key") if scene.blendermcp_hyper3d_mode == 'MAIN_SITE': sub.operator("blendermcp.set_hyper3d_free_trial_api_key", text="Set Free Trial API Key", icon='KEYINGSET') sub = self._integration_header( layout, scene, "blendermcp_use_hunyuan3d", "Tencent Hunyuan 3D", 'MESH_CUBE') if sub and premium: sub.label(text="Runs through Premium") elif sub: col = sub.column(align=True) col.prop(scene, "blendermcp_hunyuan3d_mode", text="Mode") if scene.blendermcp_hunyuan3d_mode == 'OFFICIAL_API': if prefs: col.prop(prefs, "hunyuan3d_secret_id", text="SecretId") col.prop(prefs, "hunyuan3d_secret_key", text="SecretKey") else: col.prop(scene, "blendermcp_hunyuan3d_secret_id", text="SecretId") col.prop(scene, "blendermcp_hunyuan3d_secret_key", text="SecretKey") col.prop(scene, "blendermcp_hunyuan3d_intl_pro", text="International (Pro) account") if scene.blendermcp_hunyuan3d_mode == 'LOCAL_API': if prefs: col.prop(prefs, "hunyuan3d_api_url", text="API URL") else: col.prop(scene, "blendermcp_hunyuan3d_api_url", text="API URL") col.separator() col.prop(scene, "blendermcp_hunyuan3d_octree_resolution", text="Octree Resolution") col.prop(scene, "blendermcp_hunyuan3d_num_inference_steps", text="Inference Steps") col.prop(scene, "blendermcp_hunyuan3d_guidance_scale", text="Guidance Scale") col.prop(scene, "blendermcp_hunyuan3d_texture", text="Generate Texture") sub = self._integration_header(layout, scene, "blendermcp_use_tripo", "Tripo", 'OUTLINER_OB_MESH') if sub and premium: sub.label(text="Runs through Premium") elif sub: col = sub.column(align=True) col.prop(scene, "blendermcp_tripo_model", text="Model") endpoints = tripo_endpoints(context) # The domain picker only matters for tripo3d.com (China) accounts, so # the sidebar shows it for a Chinese UI or once it is set; it is # always in the add-on preferences. show_domain = endpoints["domain"] == "com" or bpy.app.translations.locale.startswith("zh") if prefs: if show_domain: col.prop(prefs, "tripo_domain", text="Domain", translate=False) col.prop(prefs, "tripo_api_key", text="API Key") else: if show_domain: col.prop(scene, "blendermcp_tripo_domain", text="Domain", translate=False) col.prop(scene, "blendermcp_tripo_api_key", text="API Key") sub.operator("wm.url_open", text="Get Tripo API Key", icon='KEYINGSET').url = endpoints["keys"] sub = self._integration_header(layout, scene, "blendermcp_use_meshy", "Meshy", 'OUTLINER_OB_MESH') if sub and premium: sub.label(text="Runs through Premium") elif sub: col = sub.column(align=True) col.prop(scene, "blendermcp_meshy_model", text="Model") if prefs: col.prop(prefs, "meshy_api_key", text="API Key") else: col.prop(scene, "blendermcp_meshy_api_key", text="API Key") sub.operator("wm.url_open", text="meshy.ai keys", icon='URL').url = MESHY_KEY_URL # Gaussian worlds layout.separator() layout.label(text="Gaussian Worlds", icon='WORLD') if not worldlabs_supported(): # Splats need Blender 5.3, so show the option but don't offer it. box = layout.box() row = box.row() row.enabled = False row.prop(scene, "blendermcp_use_worldlabs", text="") row.label(text="World Labs", icon='WORLD') box.label(text="Needs Blender 5.3 or newer", icon='INFO') else: sub = self._integration_header(layout, scene, "blendermcp_use_worldlabs", "World Labs", 'WORLD') if sub and premium: sub.label(text="Runs through Premium") elif sub: col = sub.column(align=True) col.prop(scene, "blendermcp_worldlabs_model", text="Model") if prefs: col.prop(prefs, "worldlabs_api_key", text="API Key") else: col.prop(scene, "blendermcp_worldlabs_api_key", text="API Key") sub.operator("wm.url_open", text="World Labs keys", icon='URL').url = WORLDLABS_KEY_URL # Community section layout.separator() community_box = layout.box() col = community_box.column(align=True) # Wrap by panel width so Blender doesn't elide the phrase mid-line. ui_scale = context.preferences.system.ui_scale region_width = context.region.width if context.region else 300 chars = max(12, int((region_width - 30) / (7 * ui_scale))) for line in textwrap.wrap("Stay updated with the latest developments", chars): col.label(text=line) col.separator() row = col.row() row.scale_y = 1.3 row.operator("wm.url_open", text="Join Discord", icon='URL').url = DISCORD_URL layout.separator() draw_addon_update(layout) # Operator to set Hyper3D API Key class BLENDERMCP_OT_SetFreeTrialHyper3DAPIKey(bpy.types.Operator): bl_idname = "blendermcp.set_hyper3d_free_trial_api_key" bl_label = "Set Free Trial API Key" @classmethod def poll(cls, context): return context.scene.blendermcp_hyper3d_mode == 'MAIN_SITE' def execute(self, context): prefs = get_blendermcp_addon_preferences(context) if prefs: if not prefs.hyper3d_api_key or prefs.hyper3d_api_key == RODIN_FREE_TRIAL_KEY: prefs.hyper3d_api_key = RODIN_FREE_TRIAL_KEY else: self.report( {'INFO'}, "Using free trial for this session only; saved private key was kept." ) context.scene.blendermcp_hyper3d_api_key = RODIN_FREE_TRIAL_KEY context.scene.blendermcp_hyper3d_mode = 'MAIN_SITE' self.report({'INFO'}, "API Key set successfully!") return {'FINISHED'} # Operator to start the server class BLENDERMCP_OT_StartServer(bpy.types.Operator): bl_idname = "blendermcp.start_server" bl_label = "Connect to Claude" bl_description = "Start the MCP for Blender server to connect with Claude" def execute(self, context): global _user_stopped_server scene = context.scene server = getattr(bpy.types, "blendermcp_server", None) if server is not None and server.running: scene.blendermcp_server_running = True return {'FINISHED'} try: host = _blendermcp_bind_address(context) except ValueError as exc: scene.blendermcp_server_running = False self.report({'ERROR'}, str(exc)) return {'CANCELLED'} _user_stopped_server = False # Create a new server instance if server is None: server = BlenderMCPServer(host=host, port=scene.blendermcp_port) bpy.types.blendermcp_server = server else: server.host = host server.port = scene.blendermcp_port # Start the server server.start() scene.blendermcp_server_running = server.running return {'FINISHED'} # Operator to stop the server class BLENDERMCP_OT_StopServer(bpy.types.Operator): bl_idname = "blendermcp.stop_server" bl_label = "Stop the connection to Claude" bl_description = "Stop the connection to Claude" def execute(self, context): global _user_stopped_server _user_stopped_server = True scene = context.scene # Stop the server if it exists if hasattr(bpy.types, "blendermcp_server") and bpy.types.blendermcp_server: bpy.types.blendermcp_server.stop() del bpy.types.blendermcp_server scene.blendermcp_server_running = False return {'FINISHED'} #region Addon updates # The addon updates itself from the open-source repo. An update is offered only # when main carries a strictly newer (version, protocol), so a local build that # is ahead of main is never "updated" backwards. ADDON_UPDATE_URL = "https://raw.githubusercontent.com/ahujasid/blender-mcp/main/addon.py" ADDON_CHANGES_URL = "https://github.com/ahujasid/blender-mcp/commits/main/addon.py" ADDON_UPDATE_CHECK_ENV = "BLENDERMCP_NO_UPDATE_CHECK" _ADDON_VERSION_RE = re.compile(r'"version":\s*\((\d+)\s*,\s*(\d+)(?:\s*,\s*(\d+))?\s*\)') _ADDON_PROTOCOL_RE = re.compile(r"^ADDON_PROTOCOL_VERSION\s*=\s*(\d+)", re.MULTILINE) # status: idle | checking | current | available | installed | error _addon_update = {"status": "idle", "version": None, "source": None, "error": None} def addon_release_key(source): """(major, minor, patch, protocol) of an addon.py's text, or None if it isn't one.""" bl_info_at = source.find("bl_info = {") if bl_info_at < 0 or '"name": "MCP for Blender"' not in source[bl_info_at:bl_info_at + 200]: return None version = _ADDON_VERSION_RE.search(source, bl_info_at) protocol = _ADDON_PROTOCOL_RE.search(source) if not version or not protocol: return None return (int(version.group(1)), int(version.group(2)), int(version.group(3) or 0), int(protocol.group(1))) def addon_version_label(key): major, minor, patch, _protocol = key return f"{major}.{minor}.{patch}" if patch else f"{major}.{minor}" def _local_release_key(): return tuple(bl_info["version"]) + (0,) * (3 - len(bl_info["version"])) + (ADDON_PROTOCOL_VERSION,) def check_for_addon_update(): """Fetch addon.py from main and record whether it is newer. Runs off the main thread.""" _addon_update.update(status="checking", error=None) try: response = requests.get(ADDON_UPDATE_URL, timeout=15) if response.status_code != 200: raise RuntimeError(f"GitHub returned HTTP {response.status_code}") source = response.text remote = addon_release_key(source) if remote is None: raise RuntimeError("the file on GitHub is not an MCP for Blender addon") compile(source, "addon.py", "exec") if remote > _local_release_key(): _addon_update.update(status="available", version=remote, source=source) else: _addon_update.update(status="current", version=remote, source=None) except Exception as e: _addon_update.update(status="error", error=str(e), source=None) def _redraw_when_update_checked(): if _addon_update["status"] == "checking": return 0.5 for window in bpy.context.window_manager.windows: for area in window.screen.areas: if area.type == 'VIEW_3D': area.tag_redraw() return None def _start_addon_update_check(): """Start a check from the main thread; the sidebar redraws when it lands.""" if _addon_update["status"] == "checking": return _addon_update["status"] = "checking" threading.Thread(target=check_for_addon_update, name="blendermcp-update-check", daemon=True).start() bpy.app.timers.register(_redraw_when_update_checked, first_interval=0.5) def _addon_update_check_on_startup(): if not bpy.app.background and not os.environ.get(ADDON_UPDATE_CHECK_ENV): _start_addon_update_check() return None # one-shot timer def install_addon_update(target_path, source): """Replace the addon file, keeping the old one beside it as .bak.""" if addon_release_key(source) is None: raise ValueError("Refusing to install: not an MCP for Blender addon") compile(source, "addon.py", "exec") staged = target_path + ".new" with open(staged, "w", encoding="utf-8", newline="") as f: f.write(source) shutil.copy2(target_path, target_path + ".bak") os.replace(staged, target_path) def draw_addon_update(layout): status = _addon_update["status"] version = _addon_update["version"] here = addon_version_label(_local_release_key()) if status == "available": box = layout.box() box.label(text=f"Update available: {addon_version_label(version)}", icon='IMPORT') row = box.row() row.scale_y = 1.3 row.operator("blendermcp.update_addon", text="Update addon", icon='FILE_REFRESH') box.operator("wm.url_open", text="What's new", icon='URL').url = ADDON_CHANGES_URL elif status == "installed": box = layout.box() box.label(text=f"Updated to {addon_version_label(version)}", icon='CHECKMARK') box.label(text="Restart Blender to finish.", icon='BLANK1') else: row = layout.row(align=True) text = { "checking": f"Addon {here} · checking for updates…", "current": f"Addon {here} · up to date", "error": f"Addon {here} · couldn't check for updates", }.get(status, f"Addon {here}") row.label(text=text) row.operator("blendermcp.check_addon_update", text="", icon='FILE_REFRESH') class BLENDERMCP_OT_CheckAddonUpdate(bpy.types.Operator): bl_idname = "blendermcp.check_addon_update" bl_label = "Check for Updates" bl_description = "Check GitHub for a newer version of this addon" def execute(self, context): _start_addon_update_check() return {'FINISHED'} class BLENDERMCP_OT_UpdateAddon(bpy.types.Operator): bl_idname = "blendermcp.update_addon" bl_label = "Update Addon" bl_description = "Download the latest addon from GitHub and install it. Takes effect after a restart" def execute(self, context): source = _addon_update["source"] if _addon_update["status"] != "available" or not source: self.report({'WARNING'}, "No update is ready to install") return {'CANCELLED'} try: install_addon_update(os.path.abspath(__file__), source) except Exception as e: self.report({'ERROR'}, f"Update failed, nothing was changed: {e}") return {'CANCELLED'} _addon_update.update(status="installed", source=None) self.report({'INFO'}, "MCP for Blender updated. Restart Blender to finish.") return {'FINISHED'} #endregion # Operator to open Terms and Conditions class BLENDERMCP_OT_OpenTerms(bpy.types.Operator): bl_idname = "blendermcp.open_terms" bl_label = "View Terms and Conditions" bl_description = "Open the Terms and Conditions document" def execute(self, context): # Open the Terms and Conditions on GitHub terms_url = "https://github.com/ahujasid/blender-mcp/blob/main/TERMS_AND_CONDITIONS.md" try: import webbrowser webbrowser.open(terms_url) self.report({'INFO'}, "Terms and Conditions opened in browser") except Exception as e: self.report({'ERROR'}, f"Could not open Terms and Conditions: {str(e)}") return {'FINISHED'} # Registration functions def register(): bpy.types.Scene.blendermcp_port = IntProperty( name="Port", description="Port for the MCP for Blender server", default=9876, min=1024, max=65535 ) bpy.types.Scene.blendermcp_server_running = bpy.props.BoolProperty( name="Server Running", default=False ) bpy.types.Scene.blendermcp_auto_start_server = bpy.props.BoolProperty( name="Auto-Start Server", description="Automatically start the MCP server when Blender loads", default=True ) bpy.types.Scene.blendermcp_use_polyhaven = bpy.props.BoolProperty( name="Use Poly Haven", description="Enable Poly Haven asset integration", default=False ) bpy.types.Scene.blendermcp_use_hyper3d = bpy.props.BoolProperty( name="Use Hyper3D Rodin", description="Enable Hyper3D Rodin generatino integration", default=False ) bpy.types.Scene.blendermcp_hyper3d_mode = bpy.props.EnumProperty( name="Rodin Mode", description="Choose the platform used to call Rodin APIs", items=[ ("MAIN_SITE", "hyper3d.ai", "hyper3d.ai"), ("FAL_AI", "fal.ai", "fal.ai"), ], default="MAIN_SITE" ) bpy.types.Scene.blendermcp_hyper3d_api_key = bpy.props.StringProperty( name="Hyper3D API Key", subtype="PASSWORD", description="API Key provided by Hyper3D", default="" ) bpy.types.Scene.blendermcp_use_hunyuan3d = bpy.props.BoolProperty( name="Use Hunyuan 3D", description="Enable Hunyuan asset integration", default=False ) bpy.types.Scene.blendermcp_hunyuan3d_mode = bpy.props.EnumProperty( name="Hunyuan3D Mode", description="Choose a local or official APIs", items=[ ("LOCAL_API", "local api", "local api"), ("OFFICIAL_API", "official api", "official api"), ], default="LOCAL_API" ) bpy.types.Scene.blendermcp_hunyuan3d_intl_pro = bpy.props.BoolProperty( name="International (Pro)", description="Use the Tencent Cloud International 'Hunyuan-to-3D (Professional)' service " "(hunyuan API, region ap-singapore, PBR enabled). Enable this when your SecretId/" "SecretKey come from tencentcloud.com; leave it off for mainland AI3D 3.0 accounts", default=False ) bpy.types.Scene.blendermcp_hunyuan3d_secret_id = bpy.props.StringProperty( name="Hunyuan 3D SecretId", description="SecretId provided by Hunyuan 3D", default="" ) bpy.types.Scene.blendermcp_hunyuan3d_secret_key = bpy.props.StringProperty( name="Hunyuan 3D SecretKey", subtype="PASSWORD", description="SecretKey provided by Hunyuan 3D", default="" ) bpy.types.Scene.blendermcp_hunyuan3d_api_url = bpy.props.StringProperty( name="API URL", description="URL of the Hunyuan 3D API service", default="http://localhost:8081" ) bpy.types.Scene.blendermcp_hunyuan3d_octree_resolution = bpy.props.IntProperty( name="Octree Resolution", description="Octree resolution for the 3D generation", default=256, min=128, max=512, ) bpy.types.Scene.blendermcp_hunyuan3d_num_inference_steps = bpy.props.IntProperty( name="Number of Inference Steps", description="Number of inference steps for the 3D generation", default=20, min=20, max=50, ) bpy.types.Scene.blendermcp_hunyuan3d_guidance_scale = bpy.props.FloatProperty( name="Guidance Scale", description="Guidance scale for the 3D generation", default=5.5, min=1.0, max=10.0, ) bpy.types.Scene.blendermcp_hunyuan3d_texture = bpy.props.BoolProperty( name="Generate Texture", description="Whether to generate texture for the 3D model", default=False, ) bpy.types.Scene.blendermcp_use_sketchfab = bpy.props.BoolProperty( name="Use Sketchfab", description="Enable Sketchfab asset integration", default=False ) bpy.types.Scene.blendermcp_sketchfab_api_key = bpy.props.StringProperty( name="Sketchfab API Key", subtype="PASSWORD", description="API Key provided by Sketchfab", default="" ) bpy.types.Scene.blendermcp_use_tripo = bpy.props.BoolProperty( name="Use Tripo", description="Enable Tripo model generation", default=False, ) bpy.types.Scene.blendermcp_tripo_domain = bpy.props.EnumProperty( name="Tripo Domain", description="Tripo API region; use an API key from the selected domain", items=TRIPO_DOMAINS, default="ai", ) bpy.types.Scene.blendermcp_tripo_model = bpy.props.EnumProperty( name="Tripo Model", description="Tripo model used for each generation", items=[(ident, label, f"{label} model") for ident, label in TRIPO_MODELS.items()], default=TRIPO_DEFAULT_MODEL, ) bpy.types.Scene.blendermcp_tripo_api_key = bpy.props.StringProperty( name="Tripo API Key", subtype="PASSWORD", description="API Key provided by Tripo", default="", ) bpy.types.Scene.blendermcp_use_meshy = bpy.props.BoolProperty( name="Use Meshy", description="Enable Meshy model generation", default=False, ) bpy.types.Scene.blendermcp_meshy_model = bpy.props.EnumProperty( name="Meshy Model", description="Meshy model used for each generation", items=[(ident, label, f"{label} model") for ident, label in MESHY_MODELS.items()], default=MESHY_DEFAULT_MODEL, ) bpy.types.Scene.blendermcp_meshy_api_key = bpy.props.StringProperty( name="Meshy API Key", subtype="PASSWORD", description="API Key provided by Meshy", default="", ) bpy.types.Scene.blendermcp_use_worldlabs = bpy.props.BoolProperty( name="Use World Labs", description="Enable World Labs world generation (needs Blender 5.3 or newer)", default=False, ) bpy.types.Scene.blendermcp_worldlabs_model = bpy.props.EnumProperty( name="World Labs Model", description="World Labs model used for each world", items=[(ident, label, f"{label} model") for ident, label in WORLDLABS_MODELS.items()], default=WORLDLABS_DEFAULT_MODEL, ) bpy.types.Scene.blendermcp_worldlabs_api_key = bpy.props.StringProperty( name="World Labs API Key", subtype="PASSWORD", description="API Key provided by World Labs", default="", ) bpy.types.Scene.blendermcp_use_polypizza = bpy.props.BoolProperty( name="Use Poly Pizza", description="Enable Poly Pizza asset integration", default=False ) bpy.types.Scene.blendermcp_polypizza_api_key = bpy.props.StringProperty( name="Poly Pizza API Key", subtype="PASSWORD", description="API Key provided by Poly Pizza", default="" ) # Register preferences class bpy.utils.register_class(BLENDERMCP_AddonPreferences) bpy.utils.register_class(BLENDERMCP_PT_Panel) bpy.utils.register_class(BLENDERMCP_OT_SetFreeTrialHyper3DAPIKey) bpy.utils.register_class(BLENDERMCP_OT_StartServer) bpy.utils.register_class(BLENDERMCP_OT_StopServer) bpy.utils.register_class(BLENDERMCP_OT_OpenTerms) bpy.utils.register_class(BLENDERMCP_OT_CheckAddonUpdate) bpy.utils.register_class(BLENDERMCP_OT_UpdateAddon) for cls in PREMIUM_CLASSES: bpy.utils.register_class(cls) # Off the register path: no network until Blender has finished starting. bpy.app.timers.register(_addon_update_check_on_startup, first_interval=5.0) # Add-on registration can run before Blender has a stable UI/scene context. # Defer socket startup and retry after startup-file or .blend loads. _blendermcp_register_auto_start() print("BlenderMCP addon registered") def unregister(): _blendermcp_unregister_auto_start() _unregister_edit_capture_handlers() # Stop the server if it's running if hasattr(bpy.types, "blendermcp_server") and bpy.types.blendermcp_server: bpy.types.blendermcp_server.stop() del bpy.types.blendermcp_server bpy.utils.unregister_class(BLENDERMCP_PT_Panel) bpy.utils.unregister_class(BLENDERMCP_OT_SetFreeTrialHyper3DAPIKey) bpy.utils.unregister_class(BLENDERMCP_OT_StartServer) bpy.utils.unregister_class(BLENDERMCP_OT_StopServer) bpy.utils.unregister_class(BLENDERMCP_OT_OpenTerms) bpy.utils.unregister_class(BLENDERMCP_OT_CheckAddonUpdate) bpy.utils.unregister_class(BLENDERMCP_OT_UpdateAddon) for timer in (_addon_update_check_on_startup, _redraw_when_update_checked): if bpy.app.timers.is_registered(timer): bpy.app.timers.unregister(timer) for cls in PREMIUM_CLASSES: bpy.utils.unregister_class(cls) bpy.utils.unregister_class(BLENDERMCP_AddonPreferences) del bpy.types.Scene.blendermcp_port del bpy.types.Scene.blendermcp_server_running del bpy.types.Scene.blendermcp_auto_start_server del bpy.types.Scene.blendermcp_use_polyhaven del bpy.types.Scene.blendermcp_use_hyper3d del bpy.types.Scene.blendermcp_hyper3d_mode del bpy.types.Scene.blendermcp_hyper3d_api_key del bpy.types.Scene.blendermcp_use_sketchfab del bpy.types.Scene.blendermcp_sketchfab_api_key del bpy.types.Scene.blendermcp_use_tripo del bpy.types.Scene.blendermcp_tripo_domain del bpy.types.Scene.blendermcp_tripo_model del bpy.types.Scene.blendermcp_tripo_api_key del bpy.types.Scene.blendermcp_use_meshy del bpy.types.Scene.blendermcp_meshy_model del bpy.types.Scene.blendermcp_meshy_api_key del bpy.types.Scene.blendermcp_use_worldlabs del bpy.types.Scene.blendermcp_worldlabs_model del bpy.types.Scene.blendermcp_worldlabs_api_key del bpy.types.Scene.blendermcp_use_polypizza del bpy.types.Scene.blendermcp_polypizza_api_key del bpy.types.Scene.blendermcp_use_hunyuan3d del bpy.types.Scene.blendermcp_hunyuan3d_mode del bpy.types.Scene.blendermcp_hunyuan3d_intl_pro del bpy.types.Scene.blendermcp_hunyuan3d_secret_id del bpy.types.Scene.blendermcp_hunyuan3d_secret_key del bpy.types.Scene.blendermcp_hunyuan3d_api_url del bpy.types.Scene.blendermcp_hunyuan3d_octree_resolution del bpy.types.Scene.blendermcp_hunyuan3d_num_inference_steps del bpy.types.Scene.blendermcp_hunyuan3d_guidance_scale del bpy.types.Scene.blendermcp_hunyuan3d_texture print("BlenderMCP addon unregistered") if __name__ == "__main__": register()