Skip to main content
Glama
BIM Viewer MCP Server

BIM Viewer MCP Server

BIM Viewer MCP Server

An MCP server that lets an AI agent find and show mechanical equipment in a live 3D building model. Ask for a category, a cost ranking, or a level, and the agent highlights, isolates, or frames exactly those elements in an Autodesk Platform Services (APS) 3D viewer — and can hand back a procurement-ready list of what was found.

Built on the GSA MCP hackathon template with FastMCP, Pydantic, and uv.


What problem it solves

Facility management (FM) teams — O&M technicians, building managers, procurement analysts — reconcile asset spreadsheets against drawings by hand. Nothing links a spreadsheet line to the actual element in the building, so a count or a replacement list can't be visually verified.

This server closes that gap. An agent resolves a plain-language request ("the air terminals on Level 2", "equipment over $50k to replace") against the building's asset data, then shows the matching elements in the 3D model so the answer is verifiable, and can export the set as a procurement list keyed to each element's replacement cost.

It is read / view-only by construction: no tool edits, writes, or deletes the model.


Related MCP server: Model MCP

Repo structure

MCP_Hackathon_submission/
├── README.md                  # This file
├── QUICKSTART.md              # Clone → run the server → connect a client
├── SECURITY.md                # Security posture + GSA disclosure policy
├── main.py                    # Local entry point (uv run python main.py)
├── pyproject.toml             # Package + dependencies (uv)
│
├── src/bim_viewer_mcp/        # ← THE MCP SERVER (graded code)
│   ├── app.py                 #   Thin entry: build FastMCP, pick transport
│   ├── config.py              #   Settings from env vars / .env (Pydantic)
│   ├── models.py              #   Pydantic models, enums, allow-lists, id checks
│   ├── utils.py               #   Shared HTTP helper (fixed origin, SSRF guards)
│   ├── routes.py              #   HTTP-only routes (/health)
│   ├── tools/                 #   ONE FILE PER TOOL
│   │   ├── find_elements.py       resolve — by cost (top-N / threshold)
│   │   ├── find_by_category.py    resolve — by named category / level / room
│   │   ├── find_in_room.py        resolve — equipment inside a given room
│   │   ├── find_nearest.py        resolve — nearest N of a category to a point
│   │   ├── find_extreme.py        resolve — the largest / smallest of a category
│   │   ├── find_clearance.py      resolve — an electrical panel's working clearance
│   │   ├── find_workorders.py     resolve — work-order count / cost by filters
│   │   ├── highlight_elements.py  act — color a set in place
│   │   ├── highlight_rooms.py     act — color rooms
│   │   ├── isolate.py             act — show only a set
│   │   ├── zoom_to.py             act — move the camera
│   │   ├── reset.py               act — clear and show the whole building
│   │   └── color_by.py            (planned future tool — not registered)
│   ├── prompts/               #   Reusable conversation starters
│   └── resources/             #   Server metadata the client can read
│
├── eval/
│   ├── phoenix/               # ← THE EVALUATION (Arize Phoenix harness)
│   │   ├── run_experiment.py      run agent + judges against a dataset
│   │   ├── judges/                correctness + scope LLM judges
│   │   ├── prompts/               versioned system prompts (v1–v3)
│   │   └── datasets/              gold questions (evaluation.xml → CSV)
│   └── databricks/            # Databricks eval scaffolding
│
├── tests/                     # 45 import/registration/security smoke tests
│
├── app/                       # The demo web app (viewer backend)
│   ├── app.py                 #   FastAPI backend: asset API + WebSocket hub
│   ├── agent.py               #   Fast tool-using agent (/api/agent)
│   ├── genie.py               #   Databricks Genie path (demo fallback)
│   ├── volume_models.py       #   Streams the SVF package from a Databricks
│   │                          #   UC Volume over /dbx-models (Range-aware proxy)
│   ├── db.py, chat.py, fields.py
│   ├── static/                #   The 3D viewer (viewer.html) + assets
│   └── ModelDerivatives/      #   3D model derivatives (local fallback at /models;
│                              #   the viewer streams from a Databricks UC Volume
│                              #   via /dbx-models by default — large binaries,
│                              #   git-ignored; local demo only)
│
├── data_prep/                 # Scripts that build the synthetic asset data
│   ├── generate_ca8888_synthetic_maximo.py
│   ├── pare_revit_json_for_upload.py
│   └── setup.sql
│
├── scripts/                   # Manual end-to-end probes against a live viewer
│   ├── probe_live_viewer.py
│   └── probe_transformers.py
│
└── docs/project/              # Evaluation write-up, run guide, journey, security notes

The MCP server (src/bim_viewer_mcp/) and the evaluation (eval/phoenix/) are the deliverable code. The app/ directory is the live demo the server drives.


How the pieces fit together

Revit / BIM model (JSON)  ─┐
                           ├─►  Databricks warehouse  ─►  app/ backend  ─►  MCP server  ─►  3D viewer
Asset & cost data (synth) ─┘    (joined on asset id)      (asset API +      (find → act    (highlights the
                                                           WebSocket hub)     tools)         matching elements)
  • The model and the synthetic asset/cost data are joined in Databricks on a shared asset id; each asset row carries the element's durable Revit UniqueId (source_unique_id), which is the viewer's externalId.

  • The MCP server's resolve tools (e.g. find_elements, find_by_category, find_in_room, find_clearance, find_workorders) ask the app/ backend for the data that matches a request — the matching elements' externalIds, a count, a cost, or a clearance verdict.

  • The act tools (highlight_elements, highlight_rooms, isolate, zoom_to, reset) POST a validated command to the backend, which broadcasts it to every connected viewer over a WebSocket — so the open 3D model lights up.

The asset/cost data is synthetic, Maximo-style data, not a connection to a real Maximo system.


Getting started

Prerequisites

  • uv — pip install uv or brew install uv

Run the MCP server

cp .env.example .env
uv sync
uv run python main.py

The server starts in stdio mode — it talks JSON-RPC over stdin/stdout, which is how local clients (Claude Desktop, Claude Code) launch it. See QUICKSTART.md to connect a client.

Verify

uv sync --group dev
uv run pytest tests/ -v      # 45 tests
uv run ruff check .          # lint

Run the demo app (optional, for the live 3D viewer)

The app/ backend serves the viewer and the asset API the resolve tools call. It needs a Databricks SQL warehouse (host, warehouse id, token) in the environment. From app/:

uvicorn app:app --host 127.0.0.1 --port 8000
# then open http://127.0.0.1:8000/

By default the viewer streams the SVF package from a Databricks UC Volume over /dbx-models (a Range-aware proxy in volume_models.py), so the large model binaries do not need to live on the local disk. A local copy under app/ModelDerivatives/ (served at /models) is the offline fallback. Either way the derivatives are required only for the live demo, not for running or grading the server code.


Design principles (MCP)

  • Validated inputs. Tool parameters are Pydantic-typed with Literal allow-lists for categories and levels — the model cannot pass a raw asset_type, free-form field, or SQL.

  • Tools map to goals, not endpoints. The surface splits into resolve (find which elements a request is about) and act (drive the viewer). This "find, then act" shape is what an FM user actually does, not a thin wrapper around one REST call.

  • Durable ids only. Elements are addressed by their Revit UniqueId (the viewer's externalId), never a transient numeric id.

  • Read / view-only. No tool edits, writes, or deletes. The viewer-command surface is an explicit allow-list; the backend origin is fixed by server config, never taken from a tool argument.

  • Sanitized failures. Tools return an error dict with a hint, never a raw stack trace or upstream body.


Evaluation

The server is evaluated with an Arize Phoenix harness (see eval/phoenix/). Ten gold questions span category resolves, cost rankings, camera moves, resets, and out-of-scope refusals; two LLM judges score correctness (right tool, right targets) and scope (refuse out-of-authority requests). Re-running with the tools hidden isolates the server's contribution: +0.30 correctness (0.70 → 1.00), scope 1.0 in both configurations.

Full methodology, results, and security analysis: docs/project/EVALUATION_WRITEUP.md. To reproduce a run: docs/project/HOW_TO_RUN_THE_EVAL.md.


Security

Read/view-only by construction, synthetic data only (no PII/CUI), credentials never committed. See SECURITY.md and docs/project/SECURITY-NOTES.md.


License

MIT.

Available Tools

12 tools
find_by_categoryFind elements by categoryA
Read-onlyIdempotent

Find building elements by category; return their externalIds.

Use this to answer category/level/room questions (e.g. "air terminals on Level 2", "the cooling tower", "the water-source heat pumps"), then pass the returned external_ids to highlight_elements (to show them in place) or isolate. This tool does NOT change the view by itself.

Examples: - Air terminals on Level 2: category='air_terminals', level='Level 2' - The cooling tower: category='cooling_tower' - Heat pumps: category='heat_pumps'

Returns: {"category": str, "count": int, "elements": [{external_id, asset_type, description, level_name, room_name}]}.

Inputs: category (required), level, limit, room_name. Returns: object

find_clearanceCheck NEC working clearance for a panelA
Read-onlyIdempotent

Check an electrical panel's NEC 110.26 working clearance in 3D.

Use this to answer "is the working space in front of this panel clear?" The backend builds the code-required clearance zone(s) in true 3D and reports whether anything intrudes. Pass the returned draw block to the draw_clearance viewer command to show the zones (green clear, red intruded); this tool does NOT change the view by itself.

Target the panel either by external_id or by a description substring that must resolve to exactly one panel. If the description matches none or several, the result says so — ask the user to clarify.

The check is directional (projected off the panel's working face) when the panel is mounted on a wall or column, and an honest all-around maintenance-access check when the panel is freestanding — the mode and rule fields say which, and the all-around mode is labeled as NEC-derived guidance rather than the literal front-only rule.

Example: - By id: external_id= - By name: description="circuit breaker switchboard"

Returns: {"external_id", "asset_type", "description", "mode", "rule", "mounting_surface", "clearance": {"zones": [...]}, "intruders": [{external_id, asset_type, description}], "clear": bool|None, "draw": {...}}. clear is None when no rule is defined for the category.

Inputs: category, description, external_id. Returns: object

find_elementsFind elements by costA
Read-onlyIdempotent

Find building elements by a cost criterion; return their externalIds.

Use this to answer cost questions, then pass the returned external_ids to highlight_elements (to show them in place) or isolate. This tool does NOT change the view by itself.

Examples: - Ten most expensive: metric='replacement_cost', op='top', limit=10 - Over $50,000: metric='replacement_cost', op='gt', value=50000 - Highest maintenance: metric='maintenance_cost', op='top', limit=5

Returns: {"metric": str, "count": int, "elements": [{external_id, asset_type, description, metric_value}]}.

Inputs: op (required), metric (required), limit, value. Returns: object

find_extremeFind the most-extreme element by geometryA
Read-onlyIdempotent

Find the most-extreme element(s) by position or size.

Use this to answer superlative questions (e.g. "the largest piece of equipment", "the northmost air handler", "the smallest transformer"), then pass the returned external_ids to highlight_elements or zoom_to. This tool does NOT change the view by itself.

For largest/smallest, each element carries its volume_cuft. For compass directions the answer is simply which element is most extreme.

Examples: - Largest equipment: op='largest' - Northmost air handler: op='northmost', category='air_handlers' - Three smallest fans: op='smallest', category='fans', limit=3

Returns: {"op": str, "count": int, "elements": [{external_id, asset_type, description, level_name, volume_cuft?}]} ranked most-extreme first.

Inputs: op (required), level, limit, category. Returns: object

find_in_roomFind the assets inside a roomA
Read-onlyIdempotent

Find the tracked assets that sit inside a room's 3D volume.

Use this to answer room-contents questions (e.g. "what equipment is in room 54?", "the receptacles in the electrical room"), then pass the returned external_ids to highlight_elements or isolate. This tool does NOT change the view by itself.

Membership is by true 3D containment: an asset's bounding-box center must fall inside the room footprint AND within its floor-to-ceiling band, so assets on other floors are correctly excluded.

Examples: - Everything in room 54: room_number='54' - Just the receptacles: room_number='54', category='receptacles'

Returns: {"room": {external_id, room_name, room_number, level_name}, "count": int, "elements": [{external_id, asset_type, description, level_name}]}.

Inputs: limit, category, room_number, room_external_id. Returns: object

find_nearestFind the nearest elements to a reference elementA
Read-onlyIdempotent

Find the elements physically closest to a reference element.

Use this to answer proximity questions (e.g. "what's the nearest transformer to this panel?", "which air terminals are closest to the cooling tower?"), then pass the returned external_ids to highlight_elements or zoom_to. This tool does NOT change the view by itself.

Distance is the true 3D gap between bounding boxes in feet: 0 means the elements overlap or touch, and elements on different floors are correctly far apart.

Examples: - Nearest transformer to a panel: reference_external_id=, category='transformers' - Five closest anything: reference_external_id=, limit=5

Returns: {"reference_external_id": str, "count": int, "elements": [{external_id, asset_type, description, level_name, distance_ft}]} ordered nearest first.

Inputs: reference_external_id (required), level, limit, category. Returns: object

find_workordersCount or cost-total work ordersA
Read-onlyIdempotent

Count or cost-total maintenance work orders under fixed filters.

Use this for work-order / maintenance questions, e.g. "how many work orders on Level 2", "open work orders", "high-priority work orders on the 1st floor that service the heat pumps", "how much have we spent on HVAC work orders". All filters are optional and combine with AND.

Examples: - Work orders on Level 1: level='Level 1' - Open work orders: status='OPEN' - High-priority WSHP on Level 1: level='Level 1', asset_category='heat_pumps', priority='high' - HVAC maintenance spend: failure_class='HVAC', measure='cost'

Returns (count): {"measure": "count", "filters": {...}, "count": int, "breakdown_by_status": {status: int}}. Returns (cost): {"measure": "cost", "filters": {...}, "count": int, "total_cost": float, "total_labor_hours": float, "avg_cost": float}.

Inputs: level, status, measure, priority, +3 more. Returns: object

highlight_elementsHighlight elementsA
Read-onlyIdempotent

Highlight a set of building elements in the 3D viewer, in place.

The elements are colored where they stand; the camera does NOT move. Invalid or duplicate ids are dropped. Use this to show an answer visually; use zoom_to afterward only if the user asks to zoom.

Inputs: external_ids (required). Returns: object

highlight_roomsHighlight roomsA
Read-onlyIdempotent

Draw translucent volumes for a set of rooms/spaces in the viewer.

The room volumes are added in place; the camera does NOT move. Invalid or duplicate ids are dropped.

Inputs: space_external_ids (required). Returns: object

isolateIsolate elementsA
Read-onlyIdempotent

Isolate a set of elements: show only them and hide the rest.

A stronger focus than highlight_elements — everything outside the set is hidden. The camera does NOT move. Call reset to restore the full model.

Inputs: external_ids (required). Returns: object

resetReset viewA
Read-onlyIdempotent

Reset the viewer to a clean state showing the whole building.

Clears any element highlights, room volumes, and camera focus. Safe to call at any time; idempotent.

Returns: {"applied": bool}.

Inputs: no named parameters. Returns: object

zoom_toZoom toA
Read-onlyIdempotent

Move the camera to frame a room or a set of elements.

This is the only tool that changes the view — use it only when the user asks to zoom in on something. Provide a room via space_external_id, or a set of elements via external_ids. A room takes precedence if both are given. To frame a room it must already be highlighted (highlight_rooms).

Inputs: external_ids, space_external_id. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: highlight/isolate/zoom/reset are separate viewer actions, and the find_* tools split cleanly by criterion (cost, category, proximity, extreme, room containment, clearance, work orders). Descriptions repeatedly clarify when to use one over another, so an agent should not confuse them.

    Naming Consistency4/5

    Most names follow a predictable snake_case verb-first pattern: highlight_elements, highlight_rooms, find_elements, find_by_category, find_nearest, etc. The only minor deviations are single-verb tools like isolate and reset, plus zoom_to, but the overall convention remains readable and consistent.

    Tool Count5/5

    Twelve tools is well within a reasonable range for a BIM viewer assistant, and each tool appears to earn its place by covering a distinct query or viewer action. There is neither obvious bloat nor a suspiciously thin surface.

    Completeness4/5

    The surface covers the core BIM viewer workflow well: multiple discovery/query tools, visualization actions (highlight, isolate, zoom), reset, clearance checking, and work-order querying. Minor gaps exist, such as no obvious list_rooms/list_categories or get_element_details helper, but agents can largely work around them.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to interact with Autodesk Revit to query project data, manage elements, and execute generated code via the Model Context Protocol. It provides full compatibility with GitHub Copilot and Claude to automate BIM modeling workflows.
      13
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Open-source MCP server for Autodesk Revit 2022 to 2027: read, audit and edit live models with 89 tools, one Undo entry per change, and a workstation read-only lock.
      89
      16
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients such as Claude, Copilot and IDE agents to interrogate a building's digital twin in plain language through seven tools covering building overview, room lists, per-room design promises, diagnosed findings, room time series, sandboxed read-only SQL and BCF issue export. Answers whether each room still meets its own design intent — and why not — instead of relying on fixed thresholds.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI apps to detect MEP clashes in Autodesk Revit models and resolve them with Move or Bend predictions, applying each fix as a single undoable transaction. It also equips the AI to help users build custom agents, scripts, scheduled checks, and Revit buttons on top of the clash-resolution toolset.
      -