Skip to main content
Glama

Twinmotion MCP

by io.scanbimlabs

tm_import_rvt

Import a Revit/BIM model into the Twinmotion visualization pipeline: downloads the source file from a public URL, uploads it to an APS OSS transient bucket, and kicks off an SVF2 + thumbnail translation job. Returns the base64 URN (project_id) used by every other tm_* tool.

When to use: when a user wants to prepare a Revit (.rvt), IFC (.ifc), or other BIM/CAD model for real-time visualization in Unreal Engine / Twinmotion — typically the first step before rendering stills, defining scenes, or exporting FBX/glTF/OBJ geometry for a UE import. Also use when you need thumbnails or view metadata from a source file that has not yet been translated by APS. When NOT to use: not for MEP clash review (use navisworks-mcp), not for quantity takeoff or cost estimation (use qto-mcp), not for Twinmotion presets editing — Twinmotion itself has no public REST API, so scene/material authoring must happen manually in the UE editor after FBX/USD export. APS scopes required: data:read data:write data:create bucket:read bucket:create viewables:read. Uses Model Derivative API (translation) + OSS (upload). Twinmotion has no public REST API; all automation is APS Model Derivative + manual Unreal Engine export. Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; large .rvt/.nwd/.ifc files are often multi-GB and translation can take 5–60 min — poll the manifest with exponential backoff (start 5s, cap 60s) rather than retrying this tool. Worker request ceiling is ~100MB body; extremely large files may need signed-URL upload instead. Errors: 401 = APS token failed (check APS_CLIENT_ID/APS_CLIENT_SECRET, re-auth); 403 = scope missing (bucket:create/data:write not granted — have user re-consent); 404 = file_url unreachable; 409 = bucket key collision (rare — retry, tool uses timestamp); 413/507 = file too large for worker memory (advise signed-URL upload); 422 = unsupported source format (only Autodesk-accepted types: rvt, ifc, nwd, dwg, dgn, 3dm, stp, etc.); 429 = back off 60s before retrying; 5xx = APS upstream outage, retry with backoff. Side effects: CREATES a new transient OSS bucket (scanbim-viz-, auto-expires in 24h), CREATES an object in OSS, STARTS a translation job consuming APS cloud credits. NOT idempotent — each call creates a new bucket + URN. Writes a row to usage_log D1 table.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
file_urlYesPublic HTTPS URL to download the source BIM/CAD file. Must be reachable without auth from Cloudflare Workers egress. Supports rvt, ifc, nwd, dwg, dgn, 3dm, stp, obj, and other APS-supported formats. Signed URLs (S3/GCS) work if the signature is embedded in the query string.
file_nameYesFilename with extension used as the OSS object key. Non-alphanumeric characters are sanitized to underscores. Extension drives APS translator selection (.rvt → Revit, .ifc → IFC, etc.). For downstream Twinmotion/UE import, keep the base name meaningful (e.g. 'TowerA_L01-L20.rvt' → later exported as TowerA_L01-L20.fbx / .glb / .usd).
lighting_presetNoLighting preset label stored alongside the import — purely metadata for downstream tm_render_image / UE scene setup; does not affect the APS translation itself. 'natural' = daylight sun+sky, 'studio' = neutral 3-point, 'evening' = warm low sun.
include_materialsNoIf true (default), the translation preserves material/texture data so the derivative is visually meaningful in Twinmotion/UE. Set false only for geometry-only pipelines (faster, smaller derivatives).

Schema Changelog

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

  1. Changed8 schema fields changed
    • changedInput schema / properties / file_name / description
      Previous value: -"File name (e.g. 'Building.rvt')"New value: +"Filename with extension used as the OSS object key. Non-alphanumeric characters are sanitized to underscores. Extension drives APS translator selection (.rvt → Revit, .ifc → IFC, etc.). For downstream Twinmotion/UE import, keep the base name meaningful (e.g. 'TowerA_L01-L20.rvt' → later exported as TowerA_L01-L20.fbx / .glb / .usd)."
    • addedInput schema / properties / file_name / examples
      Added value: +[
+  "Building.rvt",
+  "SitePlan.ifc",
+  "Factory_v3.nwd",
+  "Terrain.dwg"
+]
    • changedInput schema / properties / file_url / description
      Previous value: -"Public URL to download the Revit file"New value: +"Public HTTPS URL to download the source BIM/CAD file. Must be reachable without auth from Cloudflare Workers egress. Supports rvt, ifc, nwd, dwg, dgn, 3dm, stp, obj, and other APS-supported formats. Signed URLs (S3/GCS) work if the signature is embedded in the query string."
    • addedInput schema / properties / file_url / examples
      Added value: +[
+  "https://example-cdn.com/projects/office-tower.rvt",
+  "https://storage.googleapis.com/bim-uploads/site-model.ifc?X-Goog-Signature=..."
+]
    • changedInput schema / properties / include_materials / description
      Previous value: -"Include material data in translation"New value: +"If true (default), the translation preserves material/texture data so the derivative is visually meaningful in Twinmotion/UE. Set false only for geometry-only pipelines (faster, smaller derivatives)."
    • addedInput schema / properties / include_materials / examples
      Added value: +[
+  true,
+  false
+]
    • changedInput schema / properties / lighting_preset / description
      Previous value: -"Scene lighting preset label"New value: +"Lighting preset label stored alongside the import — purely metadata for downstream tm_render_image / UE scene setup; does not affect the APS translation itself. 'natural' = daylight sun+sky, 'studio' = neutral 3-point, 'evening' = warm low sun."
    • addedInput schema / properties / lighting_preset / examples
      Added value: +[
+  "natural",
+  "studio"
+]
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

No annotations are provided, so the description carries full burden. It discloses side effects (creates transient bucket, starts translation job, consumes credits, not idempotent), rate limits, polling/backoff strategy, required APS scopes, and detailed error-code mappings. This is far beyond minimal transparency.

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?

Though long, the description is front-loaded with a clear summary sentence and then organized into labeled sections (When to use, When NOT to use, APS scopes, Rate limits, Errors, Side effects). Every sentence adds necessary context, and the structure makes it easy for an agent to scan. Appropriate length for the tool's complexity.

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?

No output schema exists, but the description explicitly states what is returned (base64 URN/project_id). It comprehensively covers prerequisites, side effects, error handling, rate limits, and parameter roles. Given the absence of annotations and output schema, this is exceptionally complete.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3. The description adds extra constraints not in the schema, such as the ~100MB worker ceiling and advisory for signed-URL upload on large files. This provides meaningful supplement to file_url semantics, warranting a 4.

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 states a specific verb+resource: 'Import a Revit/BIM model into the Twinmotion visualization pipeline' and details the full workflow (download, upload, translate). It clearly distinguishes from siblings by positioning this as the first step before rendering/scene-definition/export, and explicitly names alternatives like navisworks-mcp and qto-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?

Provides explicit when-to-use ('when a user wants to prepare a Revit/IFC/BIM model... typically the first step') and when-not-to-use ('not for MEP clash review... use navisworks-mcp') with alternative tools named. This gives an AI agent unambiguous selection criteria.

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