Skip to main content
Glama

Twinmotion MCP

by io.scanbimlabs

tm_export_video

Prepare a model for an animated walkthrough / video export by verifying the manifest is complete, then starting a secondary Model Derivative job that produces OBJ geometry (suitable for ingestion into offline rendering pipelines, Blender, or Unreal Engine). Also returns the list of available named views so the operator can stitch them into a camera path. Does NOT itself produce an mp4 — video encoding happens in the downstream UE/Twinmotion pipeline.

When to use: when a user wants a walkthrough/flythrough video of a BIM model (e.g. 'make a 30-second tour of Tower A') — this tool gets the geometry into a UE-ingestible form (.obj, plus suggests FBX/glTF/USD naming like TowerA_walkthrough.fbx for the exported asset) and enumerates named views to guide camera path authoring. When NOT to use: not to actually encode video (no runtime renderer in this worker — output must be finished in Unreal/Twinmotion/Blender), not before tm_import_rvt, not if the manifest is still 'inprogress' (the tool will short-circuit and return status='pending'). Not for still images (use tm_render_image) or clash animations (use navisworks-mcp). APS scopes required: data:read data:write viewables:read. Write scopes are needed because this kicks off a new Model Derivative translation job (OBJ + thumbnail). Rate limits: APS default ~50 req/min; Model Derivative translation jobs ~60 req/min. OBJ derivatives of large BIM models can be multi-GB and take 10–45 min — rely on manifest polling with exponential backoff, not re-calling this tool. Errors: 401/403 = token/scope (data:write commonly missing); 404 = URN not found; 409 = OBJ derivative already queued (treat as success); 422 = input format does not support OBJ output (some IFC variants / proprietary formats — fall back to FBX/glTF via a different derivative format); 429 = back off 60s; 5xx = APS upstream. Side effects: STARTS a new translation job on an existing URN (consumes APS cloud credits). Writes usage_log. NOT idempotent per-call (each call creates a new job record), but APS will dedupe identical output requests internally if manifest already contains the derivative.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
formatNoIntended final video container (metadata hint for the downstream UE/Twinmotion render step). mp4 = H.264 web-friendly, mov = ProRes for editing, webm = VP9/AV1 for web.
project_idYesBase64-URL-safe URN of a fully-translated model (manifest.status must equal 'success'). If status != success, the tool returns status='pending' without starting a job.
resolutionNoIntended final video resolution (metadata hint). 4K (3840x2160) roughly quadruples UE render time vs 1080p.
animation_nameYesHuman-readable label for the walkthrough/animation (used in downstream asset naming; suggest matching the exported video/USD filename base, e.g. 'tower_a_lobby_tour' → tower_a_lobby_tour.mp4 / .fbx / .glb / .usd).
duration_secondsNoTarget duration of the final video in seconds (integer). Used only as metadata for the downstream UE Movie Render Queue; this tool does not encode video. Typical: 15–120s.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. Changed10 schema fields changed
    • changedInput schema / properties / animation_name / description
      Previous value: -"Label for this animation/walkthrough"New value: +"Human-readable label for the walkthrough/animation (used in downstream asset naming; suggest matching the exported video/USD filename base, e.g. 'tower_a_lobby_tour' → tower_a_lobby_tour.mp4 / .fbx / .glb / .usd)."
    • addedInput schema / properties / animation_name / examples
      Added value: +[
+  "tower_a_lobby_tour",
+  "site_flythrough_v2",
+  "client_presentation_evening"
+]
    • changedInput schema / properties / duration_seconds / description
      Previous value: -"Target duration"New value: +"Target duration of the final video in seconds (integer). Used only as metadata for the downstream UE Movie Render Queue; this tool does not encode video. Typical: 15–120s."
    • addedInput schema / properties / duration_seconds / examples
      Added value: +[
+  15,
+  30,
+  60,
+  120
+]
    • changedInput schema / properties / format / description
      Previous value: -"Output video format"New value: +"Intended final video container (metadata hint for the downstream UE/Twinmotion render step). mp4 = H.264 web-friendly, mov = ProRes for editing, webm = VP9/AV1 for web."
    • addedInput schema / properties / format / examples
      Added value: +[
+  "mp4",
+  "mov"
+]
    • changedInput schema / properties / project_id / description
      Previous value: -"Base64-encoded URN"New value: +"Base64-URL-safe URN of a fully-translated model (manifest.status must equal 'success'). If status != success, the tool returns status='pending' without starting a job."
    • addedInput schema / properties / project_id / examples
      Added value: +[
+  "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6c2NhbmJpbS12aXotMTcwMDAwMDAwMC9CdWlsZGluZy5ydnQ"
+]
    • changedInput schema / properties / resolution / description
      Previous value: -"Output resolution"New value: +"Intended final video resolution (metadata hint). 4K (3840x2160) roughly quadruples UE render time vs 1080p."
    • addedInput schema / properties / resolution / examples
      Added value: +[
+  "1920x1080",
+  "3840x2160"
+]
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden and excels. It discloses side effects (starts translation job, consumes APS credits, writes usage_log, not idempotent), error codes with meanings, rate limits, and performance expectations (multi-GB, 10-45 min). It also clarifies it does not itself produce video, preventing false expectations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but extremely well-structured with sections (what, when to use, when not, scopes, rate limits, errors, side effects). Each sentence delivers critical information without redundancy. It is front-loaded with the core purpose and then logically expands into usage guidance, making every sentence earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (starts background job, has prerequisites, multiple error modes), the description is comprehensive. It covers prerequisites (manifest status, model fully translated), explains output (list of named views, status='pending' short-circuit), and lacks an output schema but still communicates return behavior. The error taxonomy and side-effect disclosure make it fully contextual for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with each parameter already having a clear description (e.g., format enum meanings, project_id URN requirements). The tool description adds no additional parameter-specific semantics beyond what the schema provides; it merely echoes some naming suggestions already present in the schema. Baseline 3 is appropriate when schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool 'prepares a model for animated walkthrough/video export' by verifying the manifest and starting a Model Derivative job to produce OBJ geometry. It explicitly distinguishes itself from actual video encoding by stating 'Does NOT itself produce an mp4', and differentiates from siblings by mentioning 'not for still images (use tm_render_image)' and 'clash animations (use navisworks-mcp)'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description has dedicated 'When to use' and 'When NOT to use' sections. It specifies using it for walkthrough/flythrough video requests, and explicitly lists exclusions: not for actual encoding, not before tm_import_rvt, not if manifest is 'inprogress', and not for still images or clash animations. It even names alternative tools, providing excellent decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Twinmotion MCP toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.8/5.0
Disambiguation5/5

Each tool targets a distinct step in the BIM visualization pipeline: importing, listing scenes, rendering images, setting environment config, and preparing video export. Their purposes are clearly separated with no overlap.

Naming Consistency5/5

All tools follow a consistent 'tm_verb_noun' pattern (e.g., tm_import_rvt, tm_list_scenes, tm_render_image). The naming is uniform and predictable.

Tool Count5/5

With only 5 tools, the server is well-scoped for a focused domain (BIM model import and visualization preparation). Each tool serves an essential function without unnecessary bloat or deficiency.

Completeness4/5

The tool set covers the main workflow (import->configure->list->render/export), but there are minor gaps: tm_export_video does not produce the final video (requires external pipeline) and there is no tool for direct FBX/glTF export or model cleanup. Still, it adequately supports the stated purpose.

Resources