Revit MCP Bridge
Connects AI agents to Autodesk Revit for inspection, interaction, and automation.
Check connection health and list/bind active Revit instances across ports.
Retrieve active model metadata (title, path, view, levels).
Execute arbitrary Revit API Python on the main UI thread (with doc, uidoc, uiapp, app, response_data).
Get current selection, element geometry (mm bounding boxes, location, rotation, levels), and model warnings.
Capture high-res screenshots and retrieve latest screenshot/snip metadata.
Request interactive user selection in Revit (with category filters, multiple, timeout).
Request user screen snip and markup for multimodal vision.
Set HUD busy state/message/activity for visual feedback.
Provides tools for interacting with Autodesk Revit, enabling AI agents to execute Python scripts via the Revit API, query and modify model elements, capture screenshots, request user selections and snips, inspect warnings and geometry, and manage multi-instance Revit sessions.
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., "@Revit MCP Bridge ask the user to pick a wall and then change its type to brick"
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.
Revit MCP Bridge for Google Antigravity
A dedicated, high-performance Model Context Protocol (MCP) bridge engineered natively for Google Antigravity (and compatible with Claude Desktop, Cursor, Cline, and Windsurf) to connect autonomous AI agents with Autodesk Revit.
Communication-First Architecture: This standalone variant delivers a pure, rock-solid communication layer for Revit automation β free of external voice/speech-to-text models, audio recording, or bloated dependencies. All multimodal interaction (visual markup, view inspection, interactive element selection) happens directly through the MCP protocol and Antigravity's multimodal reasoning engine.
π Built for Google Antigravity
Antigravity operates as an autonomous BIM engineering assistant with continuous feedback loops directly inside Autodesk Revit:
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Google Antigravity AI Agent β
β (Autonomous BIM Coding & Multimodal Vision) β
βββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββ
β stdio (MCP JSON-RPC)
βββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββ
β Revit MCP Server Bridge (Python) β
β revit_mcp/server.py β
βββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββ
β HTTP / JSON (127.0.0.1:40001+)
βββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββ
β Autodesk Revit (pyRevit) β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Revit MCP Floating HUD (Visual State & Control) β β
β β - π― Interactive Pick Elements (User Input) β β
β β - βοΈ Screen Snip & Visual Markup (Multimodal) β β
β β - π‘οΈ Modal Dialog Lock Detection β β
β β - π¦ Live Busy/Idle State Indicator β β
β ββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββ β
β β ExternalEvent β
β ββββββββββββββββββββββββββΌββββββββββββββββββββββββββ β
β β Revit Main UI Thread Execution Engine β β
β β (doc, uidoc, uiapp, app, Transactions) β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββ β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββKey Antigravity Agent Capabilities
Two-Way Interactive User Requests:
π― Interactive Element Picking (
revit_request_user_selection): When Antigravity needs the user to designate a specific element (e.g., room boundary, clashing pipe, equipment), the Revit HUD button flashes gold/purple. The user clicks the element in Revit, and its ID, category, and metadata are immediately returned to Antigravity without manual typing.βοΈ Visual Snip & Markup (
revit_request_user_snip): Antigravity can ask the user to visually circle or annotate areas of interest. The user draws arrows/boxes using the built-in screen snipper, and the annotated image is piped straight into Antigravity's vision context.
Visual Busy State Lifecycle (
revit_set_busy):The Revit HUD panel turns Gray while Antigravity is processing or executing transactions, and switches back to Green when Antigravity is done and awaiting user input.
Modal Dialog Safety:
If a modal window opens in Revit (e.g. warning dialog or file dialog), Revit MCP immediately detects it via Win32 API and returns
HTTP 423 Locked, alerting Antigravity instead of hanging the agent indefinitely.
Deterministic Multi-Instance Binding:
Running multiple Revit versions or multiple documents concurrently? Each instance binds to an incremental port (
40001,40002, ...), and Antigravity locks its session strictly to the target model without accidental cross-project execution.
Related MCP server: Revit MCP Server
π Features
β‘ Direct Revit API Execution: Run arbitrary Python scripts on the Revit main UI thread safely using
ExternalEvent. Accessdoc,uidoc,uiapp, andapp.π Multi-Instance Support: Multiple open Revit models automatically receive incremental ports (
40001,40002, ...).π― Interactive Element Selection: AI agents can ask the user to pick elements in Revit (
revit_request_user_selection).βοΈ Visual Screen Snip & Markup: Prompt the user to snip screen regions and annotate them with arrows, boxes, and freehand sketches (
revit_request_user_snip).π‘οΈ Modal Dialog Protection: Win32 detection checks whether Revit is blocked by a modal dialog, reporting HTTP 423 Locked instead of freezing requests indefinitely.
πΈ Automated High-Res Screenshots: Capture the active Revit view as a PNG image directly into the agent's context.
πͺ Minimal Floating HUD: Clean WPF window displaying server status, active port, request counter, latency, pin (always-on-top), and compact minimize mode.
π Quick Start
Step 1: Install the pyRevit Extension
You can install the RevitMCP extension into pyRevit centrally using any of the methods below:
Option A: Central CLI Installation (Recommended β 1 Command)
Run in PowerShell / Command Prompt:
pyrevit extend ui RevitMCP https://github.com/AndreyStartsev/revit-mcp.gitTo update in the future:
pyrevit extensions update RevitMCPOption B: Central pyRevit Extension Manager (GUI)
Register the repository source centrally in pyRevit:
pyrevit extensions sources add https://raw.githubusercontent.com/AndreyStartsev/revit-mcp/main/pyrevit_source.jsonNow open Autodesk Revit, navigate to pyRevit > Settings > Extensions, select RevitMCP, and click Install.
π‘ Official pyRevit catalog submission: Pull Request #3719 is currently open in
pyrevitlabs/pyRevit(see details in PYREVIT_PROPOSAL.md).
Option C: Manual Installation
Clone or copy this repository directly into your pyRevit extensions folder:
# Default pyRevit extension directory:
git clone https://github.com/AndreyStartsev/revit-mcp.git "%APPDATA%\pyRevit\Extensions\RevitMCP.extension"Once installed, click the Revit MCP button on the ribbon tab to start the server. The floating HUD will appear and display Ready for commands on 127.0.0.1:40001.
Step 2: Install the Python MCP Server
Clone this repository and install dependencies:
git clone https://github.com/AndreyStartsev/revit-mcp.git
cd revit-mcp
# Install dependencies or install in editable mode
pip install -e .Verify connection to Revit:
python tests/test_connection.pyStep 3: Connect & Activate Your AI Agent
π€ Google Antigravity (Primary & Fully Supported)
Google Antigravity is the primary, first-class autonomous agent environment designed to work seamlessly with Revit MCP out-of-the-box.
1. Register the MCP Server in Antigravity
Open or create your global Antigravity MCP configuration:
Windows:
%USERPROFILE%\.gemini\config\mcp_config.json(or your workspace MCP configuration)
Add the revit server entry:
{
"mcpServers": {
"revit": {
"command": "python",
"args": ["-m", "revit_mcp"]
}
}
}(If you are running in a dedicated virtual environment or pyRevit CPython, specify the full path to python.exe).
2. Automatic Agent Guidelines (GEMINI.md)
Antigravity automatically discovers and ingests GEMINI.md from the root of this workspace. This equips the agent with:
Visual HUD State Tracking: The agent automatically invokes
revit_set_busy(busy=True)at the very start of its reasoning to turn the floating HUD gray, and callsrevit_set_busy(busy=False)upon completing its response.Strict Transaction Handling: Safe wrapping in
Transaction(doc, ...), rollback on errors, and suppression of modal blocking dialogs viaIFailuresPreprocessor.Multimodal Interaction: Native capability to trigger interactive element selection (
revit_request_user_selection) and visual markup requests (revit_request_user_snip).Coordinate & Level Normalization: Relative elevation anchoring ($Z_{\text{rel}} = Z_{\text{world}} - Z_{\text{host_level}}$) and linked model transform handling.
Spatial Integrity: Strict protection against unauthorized element movement or rotation.
3. Activate & Verify in Antigravity Chat
Launch Autodesk Revit and open your project.
Click the Revit MCP button on the ribbon tab to launch the server and floating HUD (displays
Readyon127.0.0.1:40001).In Antigravity chat, send a verification prompt:
"Check the active Revit model, report connection status, and list available views."
You will see the floating HUD turn Gray while Antigravity reasons and executes tools, and return to Dark/Ready when the response is delivered.
π‘ Advice for Other Agentic Systems (Claude Desktop, Cursor, Cline, Windsurf)
While this bridge is optimized natively for Google Antigravity, it complies with the open Model Context Protocol standard and can be connected to other MCP clients:
Client Configuration:
Claude Desktop (
%APPDATA%\Claude\claude_desktop_config.jsonon Windows):{ "mcpServers": { "revit": { "command": "python", "args": ["-m", "revit_mcp"] } } }Cursor (
.cursor/mcp.json) / Cline / Windsurf: Add the samemcpServersdefinition into your client's MCP configuration settings.
System Prompt / Rules Porting:
Other clients do not automatically read
GEMINI.md. To achieve the same reliability:Cursor: Copy the rules from
GEMINI.mdinto your.cursorrulesor.cursor/rules/revit.mdc.Claude Desktop: Append the rules into Project Custom Instructions or your initial prompt.
Cline / Windsurf: Add the rules into your
.clinerulesor workspace instructions.
Critical Rule to Include: Instruct the agent to always wrap Revit API modifications in
Transaction(doc, ...)and attach anIFailuresPreprocessorso modal dialogs don't freeze the client.
Multimodal Capabilities:
For visual tools (
revit_capture_screenshotandrevit_request_user_snip), ensure your agent is configured with a vision-capable multimodal model (e.g., Claude 3.5 Sonnet, GPT-4o, or Gemini 1.5 Pro).
π οΈ Available MCP Tools
Tool | Description |
| Checks connection health and reports the active Revit instance and document. |
| Lists all active Revit instances across ports |
| Binds the session to a specific instance by port or model name. |
| Retrieves metadata about the active model (title, path, view, levels). |
| Executes arbitrary Python in Revit via Revit API ( |
| Returns currently selected elements, categories, and parameters. |
| Retrieves exact bounding boxes (mm), locations, rotations, and levels. |
| Retrieves all active model warnings and failing element IDs. |
| Captures an automated high-resolution PNG of the active Revit view. |
| Retrieves metadata and file path of the most recent screenshot or snip. |
| Prompts user in Revit to click element(s) with optional category filtering. |
| Prompts user to snip screen area and annotate with built-in markup tools. |
| Controls the visual busy indicator and theme color in the Revit HUD. |
π‘ Python Execution Pattern
When using revit_execute_python, you write standard Revit API Python code. Always use transactions when modifying the model:
from Autodesk.Revit.DB import Transaction, FilteredElementCollector, BuiltInCategory
# 1. Access objects in scope: doc, uidoc, uiapp, app
collector = FilteredElementCollector(doc).OfCategory(BuiltInCategory.OST_Walls).WhereElementIsNotElementType()
# 2. Modify with Transaction
t = Transaction(doc, "Set Comments")
t.Start()
for wall in collector:
param = wall.LookupParameter("Comments")
if param and not param.IsReadOnly:
param.Set("Verified by Antigravity")
t.Commit()
# 3. Return results via response_data
response_data["wall_count"] = collector.GetElementCount()
response_data["status"] = "Success"π₯οΈ Direct Python Client
If you want to communicate with Revit without an MCP client (for testing or automation scripts), use the included RevitClient:
from revit_mcp import RevitClient
client = RevitClient(port=40001)
# Health check
print(client.ping())
# Execute code
res = client.execute_python("""
response_data['doc_title'] = doc.Title if doc else 'No Document'
""")
print(res['data'])π Security & Concurrency Architecture
Shared Secret Authentication: On startup, Revit MCP generates a cryptographically random session token (
auth_token). All incoming HTTP API requests requireAuthorization: Bearer <token>orX-Auth-Token.Zero CORS Vulnerability: By design, all
Access-Control-Allow-*CORS headers are removed, ensuring web browsers cannot perform cross-origin script executions from malicious websites.Thread-Safe FIFO Execution Queue: Remote commands are enqueued in a thread-safe FIFO queue (
collections.dequeprotected by locks). Each request awaits its ownManualResetEvent, eliminating race conditions when multiple agents or subagents query Revit concurrently.Cross-Version pyRevit & .NET 8 Compatibility: Modeless window management and external event handling are verified across pyRevit 4.x, 5.x, and 7.x on .NET Framework 4.8 and modern .NET 8 (Revit 2023β2027).
π License
This project is licensed under the MIT License.
Available Tools
13 toolsrevit_capture_screenshotC
Triggers and captures a high-resolution screenshot of the currently active view in Revit.
Inputs: port, doc_name. Returns: result
revit_execute_pythonA
Executes arbitrary Python code inside Autodesk Revit on the main UI thread.
Provides:
doc: Active Revit Document
uidoc: Active UIDocument
uiapp: UIApplication
app: Application
response_data: Dict to store return values (e.g. response_data['my_key'] = ...)
Always wrap model modifications in a Transaction: t = Transaction(doc, 'Action Name') t.Start() ... t.Commit()
Inputs: code (required), port, doc_name. Returns: result
revit_get_active_modelB
Retrieves metadata about the currently open model in the bound Revit instance (title, file path, active view, level).
Inputs: port, doc_name. Returns: result
revit_get_element_geometryC
Retrieves high-precision geometric summary (exact mm bounding box, location, rotation, level elevation) for elements.
Inputs: port, doc_name, element_ids. Returns: result
revit_get_latest_screenshotA
Retrieves metadata and file path of the most recently captured screenshot or user snip.
Inputs: no named parameters. Returns: result
revit_get_selectionC
Retrieves information about currently selected elements in the bound Revit document.
Inputs: port, doc_name. Returns: result
revit_get_warningsC
Retrieves all active model warnings from the bound Revit instance.
Inputs: port, doc_name. Returns: result
revit_list_instancesA
Lists all currently active Autodesk Revit instances across all ports and indicates which instance is bound.
Inputs: no named parameters. Returns: result
revit_pingB
Checks connection health of the Revit MCP Server and reports the active instance.
Inputs: port, doc_name. Returns: result
revit_request_user_selectionA
Proactively requests the user in Autodesk Revit to select elements. The HUD button 'Pick Elements' will flash and wait for user clicks.
Args: prompt: Instruction shown to user in Revit HUD (e.g. 'Select the room boundary'). categories: Optional list of category names to restrict selection (e.g. ['Rooms', 'Walls']). multiple: If False, single click picks element instantly. If True, user picks multiple elements and clicks 'Finish'. timeout: Maximum seconds to wait (default 90).
Inputs: prompt (required), port, timeout, doc_name, +2 more. Returns: result
revit_request_user_snipC
Proactively requests the user in Autodesk Revit to snip a region on screen and add drawings/annotations.
Inputs: prompt (required), port, timeout, doc_name. Returns: result
revit_set_active_instanceA
Binds this session to a specific Revit instance/model (by port or document title). All subsequent operations will execute on this instance.
Inputs: port, doc_name. Returns: result
revit_set_busyC
Sets the visual busy indicator and background color of the Revit MCP HUD.
Inputs: busy, port, message, activity, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 13 tools
Each tool targets a distinct action or resource: screenshot capture, user selection request, user snip request, HUD state, instance management, model metadata, code execution, selection retrieval, geometry retrieval, and warnings. The potential overlap between capturing screenshots and retrieving the latest screenshot is resolved by clear action boundaries, and requesting selection versus getting current selection is explicitly differentiated.
All tools use snake_case with a consistent revit_ prefix, and most follow a verb_noun pattern. Minor deviations exist: revit_ping is verb-only and revit_set_busy uses an adjective rather than a noun, but overall the set is highly predictable.
The 13 tools are well-scoped for a Revit bridge that handles instance management, user interaction, screenshots, model inspection, and Python execution. No tool appears redundant, and the count fits comfortably within a focused operational set.
The surface covers core bridge workflows including connection management, user-driven selection/snipping, screenshot capture, model metadata, selection/geometry retrieval, warnings, and arbitrary Python execution for modifications. Direct CRUD tools for elements and transaction helpers are absent, but revit_execute_python provides a broad escape hatch.
Maintenance
Related MCP Connectors
Read and edit the Revit 2024β2027 model on your PC. Needs the free Revit MCP add-in.
Convert Revit files to XKT, IFC, or DWG and query BIM data via natural language.
Connect your AI assistant to Revnu, your autonomous growth agent for outbound sales, SEO, content, social media and ads. Use this MCP connector to read leads and campaign results, review and approve queued work, hand jobs to your Revnu agent, and schedule recurring workflows from your AI chat. Supports Streamable HTTP and OAuth with permissions you choose at sign-in. Tools act on your connected Revnu account; write actions require explicit permissions. Learn more and connect at https://revnu.com/mcp.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Related MCP Servers
- AlicenseAqualityFmaintenanceAllows AI to interact with Autodesk Revit via the MCP protocol, enabling retrieval of project data and automation of tasks like creating, modifying, and deleting elements.1359 npm477MIT
- AlicenseBqualityNot gradedmaintenanceAllows AI assistants to interact with Autodesk Revit through the MCP protocol, enabling the AI to create, modify, and delete elements in Revit projects.1559 npm1-
- AlicenseAqualityFmaintenanceEnables AI to interact with Revit via MCP, allowing data retrieval and element creation, modification, and deletion.1359 npmMIT
- -licenseNot gradedqualityNot gradedmaintenanceConnects MCP clients like Claude, Codex, and Cursor to a running Autodesk Revit session for typed BIM queries, verified model edits, family authoring, exports, and Power BI workflows. It is open-source, Apache-2.0, and designed for reliable, verified outcomes.-