BIM Viewer MCP Server
Drives an Autodesk Platform Services (APS) 3D building viewer: the server's resolve tools find mechanical equipment by category, cost, level, room, proximity, clearance or work orders, and its act tools highlight, isolate, zoom to, or reset those elements in the live viewer over a WebSocket, so an agent can visually verify answers against the building model.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@BIM Viewer MCP Server Show me the air terminals on Level 2 and zoom to them"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 notesThe 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'sexternalId.The MCP server's resolve tools (e.g.
find_elements,find_by_category,find_in_room,find_clearance,find_workorders) ask theapp/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 uvorbrew install uv
Run the MCP server
cp .env.example .env
uv sync
uv run python main.pyThe 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 . # lintRun 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
Literalallow-lists for categories and levels — the model cannot pass a rawasset_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 toolsfind_by_categoryFind elements by categoryARead-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 panelARead-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 costARead-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 geometryARead-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 roomARead-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 elementARead-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 ordersARead-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 elementsARead-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 roomsARead-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 elementsARead-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 viewARead-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 toARead-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
Scored across 12 tools
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.
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.
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.
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
Related MCP Connectors
AI clash detection in Navisworks Manage 2025–2027 on your PC. Needs the free plug-in.
AI for Revit: 450+ tools, 1 undo step. Windows, Revit 2024–2027 (2021–2023 included). Free account.
Read, query, edit and render DWG drawings with AI. No AutoCAD required.
AI Hub for AEC — 50+ 3D formats, clash detection, ACC integration via Autodesk Platform Services.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.13MIT
- AlicenseBqualityBmaintenanceOpen-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.8916MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- FlicenseNot gradedqualityCmaintenanceEnables 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.-