Skip to main content
Glama

Twinmotion MCP

by io.scanbimlabs

tm_set_environment

Configure the visualization environment (weather, time-of-day, surround context) for a previously imported model. Validates the model exists via APS Model Derivative manifest, then stores the environment config in KV (24h TTL) so tm_render_image and tm_export_video can apply it.

When to use: after tm_import_rvt completes and the manifest status is 'success' (or in-progress if you just want to pre-stage config), when the user wants to set scene context — e.g. 'render the tower at 17:00 in an urban setting with clear weather' — before generating images or video walkthroughs. Typical step 2 in the Twinmotion flow. When NOT to use: not for editing geometry, materials, or UE post-process volumes (those live in the Unreal Engine editor after FBX/USD import — Twinmotion has no public REST API). Do not call before tm_import_rvt — there is no URN to attach config to. APS scopes required: viewables:read data:read (manifest + metadata fetch only — read-only for this tool). No bucket or write scopes needed. Rate limits: APS default ~50 req/min per app per endpoint; manifest/metadata are cheap but polling-heavy if the model is still translating — prefer a single call per user intent, not a status-poll loop. KV writes are effectively unlimited at this scale. Errors: 401 = APS token expired/invalid; 403 = viewables:read not granted; 404 = URN unknown to APS (wrong project_id, or translation never started); 409 = n/a; 422 = n/a; 429 = back off 30s; 5xx = APS Model Derivative outage. Side effects: WRITES the env config to KV under key env_config_ (TTL 86400s). Idempotent — calling again overwrites the prior config. Writes a row to usage_log.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
weatherNoWeather condition label stored with the scene config. Drives UE sky/atmosphere presets during manual Twinmotion scene authoring.
project_idYesBase64-URL-safe URN returned by tm_import_rvt (the `project_id` / `urn` field). This is the Autodesk design URN — NOT an object ID, NOT a bucket key. Format: base64url of 'urn:adsk.objects:os.object:<bucket>/<object>', trailing '=' stripped.
environmentNoSurround/context preset for the UE scene. Purely metadata — applied when the operator builds the Twinmotion scene post-FBX-export. 'custom' means the user will supply their own HDRI/backdrop in UE.
time_of_dayNo24-hour clock time as HH:MM. Used for sun position in the UE scene. Default if omitted is '12:00' (noon).

Schema Changelog

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

  1. Changed8 schema fields changed
    • changedInput schema / properties / environment / description
      Previous value: -"Environment preset"New value: +"Surround/context preset for the UE scene. Purely metadata — applied when the operator builds the Twinmotion scene post-FBX-export. 'custom' means the user will supply their own HDRI/backdrop in UE."
    • addedInput schema / properties / environment / examples
      Added value: +[
+  "urban",
+  "natural"
+]
    • changedInput schema / properties / project_id / description
      Previous value: -"Base64-encoded URN of the translated model"New value: +"Base64-URL-safe URN returned by tm_import_rvt (the `project_id` / `urn` field). This is the Autodesk design URN — NOT an object ID, NOT a bucket key. Format: base64url of 'urn:adsk.objects:os.object:<bucket>/<object>', trailing '=' stripped."
    • addedInput schema / properties / project_id / examples
      Added value: +[
+  "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6c2NhbmJpbS12aXotMTcwMDAwMDAwMC9CdWlsZGluZy5ydnQ"
+]
    • changedInput schema / properties / time_of_day / description
      Previous value: -"Time of day (e.g. '14:30')"New value: +"24-hour clock time as HH:MM. Used for sun position in the UE scene. Default if omitted is '12:00' (noon)."
    • addedInput schema / properties / time_of_day / examples
      Added value: +[
+  "08:30",
+  "14:30",
+  "17:45"
+]
    • changedInput schema / properties / weather / description
      Previous value: -"Weather condition"New value: +"Weather condition label stored with the scene config. Drives UE sky/atmosphere presets during manual Twinmotion scene authoring."
    • addedInput schema / properties / weather / examples
      Added value: +[
+  "clear",
+  "sunset"
+]
  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 the full burden and does so thoroughly. It discloses the KV write side effect with TTL, idempotency, usage_log write, required APS scopes, rate limits, error code meanings, and the validation-before-write behavior. It also clarifies that APS permissions are read-only despite the KV side effect, preventing false assumptions.

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 tightly structured with labeled sections (when to use, when not, scopes, rate limits, errors, side effects). Every sentence provides actionable information; there is no filler or redundancy. The front-loaded purpose sentence immediately establishes the tool's essence, and the rest expands with necessary operational details.

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?

For a tool with no annotations and no output schema, the description is impressively complete. It covers prerequisites, usage flow, authentication requirements, error handling, rate limits, side effects, and idempotency. An agent has everything needed to decide when and how to call this tool, and what to expect afterward.

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?

Input schema coverage is 100% and each parameter already has a descriptive explanation, enum values, and examples. The description adds context about how parameters collectively feed the scene config but does not materially go beyond the schema's per-parameter semantics. Baseline 3 is appropriate since the schema handles parameter documentation.

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?

The description opens with a specific verb+resource+scope: 'Configure the visualization environment (weather, time-of-day, surround context) for a previously imported model.' It clearly differentiates from siblings by stating the config is stored for tm_render_image and tm_export_video to apply, and identifies its role as step 2 in the Twinmotion flow.

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 explicitly states when to use it (after tm_import_rvt completes, optionally pre-staging config even if manifest is in-progress) and when NOT to use it (editing geometry/materials/UE post-process volumes, or before import). It names sibling tools as the intended consumers and gives a concrete user-intent example, leaving no ambiguity about alternatives.

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