Ask Your Revit Model Anything: Natural Language BIM Queries with MCP
How I built a bridge between Claude AI and Autodesk Revit using Model Context Protocol, turning complex BIM data extraction into simple conversation.
The Problem Every AEC Professional Knows
You're in the middle of a design review. Someone asks: "How many doors are on Level 2?" Simple question. Getting the answer? Not so simple.
You open Revit. Navigate to a schedule view—or create one if it doesn't exist. Set up the correct category filter. Add a level parameter filter. Count the rows. 5-10 minutes gone for a question that should take seconds.
Now multiply that by every coordination meeting, every client question, every compliance check. Architects and engineers spend a staggering amount of time not designing, but extracting data from their own models.
Open Revit schedule → set category filter → add level parameter → configure columns → count rows manually → repeat for every question. Each query takes 5-10 minutes and requires deep knowledge of Revit's UI.
Type "How many doors are on Level 2?" in Claude. Get the answer in under 2 seconds. Move on with your design review.
What if you could just ask?
What This Looks Like in Practice
With the Revit-Claude MCP Bridge running, your workflow becomes a conversation. Here are real queries you can run against a live Revit model:
Simple counting:
"How many doors are on Level 2?"
Claude responds instantly: "There are 16 doors on Level 2."
Deep property inspection:
"Show me all properties of Door ID 1694190"
Everything comes back: width, height, fire rating, level, family name, type parameters—all properties, both instance and type.
Quantitative analysis:
"What is the total area of all walls in this project?"
Claude calculates: "11,596 square meters (124,835 square feet) across 1,128 wall elements."
Complex queries with formatting:
"Create a table of rooms larger than 30 m², sorted by size. Also show their levels."
Claude fetches the room data, filters, sorts, and formats it into a clean table—all from live model data.
No schedules. No filters. No manual counting. Just ask.
Why MCP Changes Everything for AEC
Model Context ProtocolDefinitionAn open standard from Anthropic that defines how AI assistants connect to external tools and data sources. MCP servers expose capabilities that AI clients like Claude Desktop can discover and invoke. is what makes this possible. Before MCP, connecting AI to desktop applications like Revit meant building fragile, custom integrations with no standardization.
MCP provides a clean contract: the AI discovers available tools, understands their parameters, and calls them when a user's question requires external data. The AI handles the natural language understanding. The tools handle the data retrieval. Neither needs to know the internals of the other.
For the AEC industry, this is significant. BIM tools like Revit hold enormous amounts of structured data—geometry, parameters, relationships, metadata—but accessing that data has always required knowing the software's interface. MCP makes the data accessible through language.
The Revit API is powerful but requires C# development, understanding of Revit's threading model, and direct integration into the desktop application. MCP provides a standardized protocol layer that any AI client can use, without needing to understand Revit internals. Build the bridge once, and any MCP-compatible AI can query your models.
The Architecture: Three Layers, One Conversation
The system consists of three components that work together to turn a natural language question into a Revit API call and back:
Layer 1: Claude Desktop
The user interface. You type questions, Claude parses intent, identifies which Revit tool to call, and formats the response into natural language. Claude discovers available tools automatically through MCP's tool discovery mechanism—no configuration beyond the initial setup.
Layer 2: MCP Server (TypeScript/Node.js)
The translator. This server speaks MCP protocol on one side (JSON-RPC over stdio) and REST HTTP on the other. It defines four core tools that Claude can invoke:
| Tool | What It Does | Example |
|---|---|---|
get_project_info | Project metadata and document info | "What project is open?" |
get_elements_by_category | Query elements with optional level filter | "List all doors on Level 2" |
get_element_properties | Detailed properties of a specific element | "Show properties of wall 123456" |
calculate_quantities | Aggregate length, area, volume, count | "Total area of all floors" |
Layer 3: Revit Add-in (C#/.NET)
The bridge to BIM data. A lightweight HTTP server running inside Revit that receives requests, queues them for thread-safe execution, and returns JSON responses. This is where the hard engineering problem lives.
The Hard Part: Revit's Threading Model
Building this wasn't a straightforward REST API. Revit's API has a fundamental constraint: all API calls must happen on the main UI thread. You cannot call FilteredElementCollector or read element parameters from a background thread. Doing so crashes Revit.
But the HTTP server must run on a background thread—otherwise it would block Revit's UI. This creates a classic producer-consumer problem that requires careful synchronization.
The solution is the ExternalEvent patternDefinitionRevit's mechanism for safely executing code on the main UI thread from an external trigger. An ExternalEvent is raised from any thread, and Revit invokes the associated handler on the main thread during its next idle cycle.—Revit's sanctioned way to cross the thread boundary.
Here's the core mechanism: when an HTTP request arrives, the server creates a TaskCompletionSource (a promise that will be fulfilled later), enqueues the request, and raises the ExternalEvent. The HTTP thread then awaits the task. On Revit's main thread, the event handler dequeues the request, executes the Revit API calls, and signals completion. The HTTP thread unblocks and sends the response.
This happens in under 2 seconds for typical queries. No UI freezing, no thread violations, no crashes.
Revit transactions are for write operations (creating/modifying elements). Read-only queries don't need transactions, but they still require main thread access. The ExternalEvent pattern is necessary regardless of whether you're reading or writing—it's about thread safety, not data integrity.
What You Can Query: 40+ Categories
The bridge supports over 40 Revit element categories out of the box. Category names are user-friendly—you say "Walls," the system maps it to BuiltInCategory.OST_Walls internally.
Architectural: Walls, Doors, Windows, Floors, Ceilings, Roofs, Stairs, Railings, Ramps, Curtain Walls
Structural: Columns, Structural Columns, Beams, Structural Framing, Foundations
MEP: Mechanical Equipment, Electrical Equipment, Lighting Fixtures, Ducts, Pipes, Conduits, Cable Trays
Spaces: Rooms, Areas, Spaces
Furniture: Furniture, Casework, Specialty Equipment, Plumbing Fixtures
Site & Annotation: Topography, Parking, Planting, Grids, Levels, Generic Models
Each query can filter by level, request specific properties, and limit results. The system automatically converts Revit's internal units (feet) to metric.
The Data Flow: From Question to Answer
Let's trace a complete query to see every step:
User asks: "How many walls are on Level 1?"
Step 1 — Intent Parsing. Claude identifies the need for element data, selects get_elements_by_category, and constructs the tool call with category: "Walls" and level: "Level 1".
Step 2 — MCP to HTTP. The MCP server translates the tool call into an HTTP POST to localhost:8080/api/revit/elements with the appropriate JSON payload. Retry logic and circuit breaker patterns protect against transient failures.
Step 3 — Queue and Execute. The Revit add-in enqueues the request and raises an ExternalEvent. On the next Revit idle cycle, the handler dequeues and executes:
var collector = new FilteredElementCollector(doc)
.OfCategory(BuiltInCategory.OST_Walls)
.WhereElementIsNotElementType();Level filtering, property extraction, and unit conversion happen on the main thread. Results are serialized to DTOs.
Step 4 — Response. JSON flows back through HTTP to the MCP server, which formats it as an MCP tool response. Claude receives structured data and generates the natural language answer.
Total round-trip time: 500ms to 2 seconds, depending on model complexity.
Setting It Up
The setup is straightforward—three components, under 10 minutes:
1. Install the Revit Add-in. Copy the .addin manifest and compiled binaries to Revit's addins folder. When Revit starts, the add-in initializes the HTTP server on localhost:8080.
2. Configure Claude Desktop. Add the MCP server to Claude's configuration:
{
"mcpServers": {
"revit": {
"command": "node",
"args": ["/path/to/packages/mcp-server/build/index.js"]
}
}
}3. Start Revit. Open a project. The add-in starts automatically. Claude discovers the four tools and is ready to answer questions about your model.
The built-in Health Monitor UI (accessible from within Revit) shows real-time status of both the add-in and MCP server, request counts, uptime, and live logs from both components. If you update the MCP server code, you can rebuild and restart Claude Desktop directly from the Health Monitor.
Resilience by Design
A multi-layer architecture means multiple points of failure. The system handles each one:
Revit not running: MCP server returns a clear message — "Revit not running or add-in not loaded."
Operation timeout: Long queries get a timeout — "Revit operation took too long, try a simpler query."
Invalid parameters: Validation catches bad input before it reaches Revit — "Unknown category: Wallz" with suggestions.
Revit restart: The MCP server includes health check polling with auto-reconnect. Close and reopen Revit, and the connection reestablishes automatically.
Connection pooling, exponential backoff retries, and circuit breaker patterns in the HTTP client ensure the system degrades gracefully rather than crashing.
Why I Built This From Scratch
There are other libraries connecting AI to Revit. I looked at them. None combined what I needed: a clean architecture with proper thread safety, a fully self-contained Revit add-in, and an MCP server that follows the protocol specification correctly.
Most existing solutions either bypass Revit's threading constraints (causing crashes under load), require external services or cloud infrastructure, or implement custom protocols that lock you into a specific AI provider.
This bridge is:
- Self-contained — everything runs locally, no cloud dependencies
- Standards-based — MCP protocol means any compatible AI client works
- Thread-safe — ExternalEvent pattern, no API violations, tested under concurrent load
- Extensible — adding a new tool means one TypeScript file and one C# route handler
Adding a new query tool follows a consistent pattern: define the MCP tool schema in TypeScript, create an HTTP route handler in C#, implement the Revit API logic in the query service, and register both ends. The existing four tools serve as templates.
What's Next
The current implementation covers read-only queries—asking questions about your model. The roadmap includes:
Write operations — creating and modifying elements through natural language. "Add a door to the wall on the east side of Room 201." This requires transaction management and user confirmation for destructive operations.
3D visualization — generating preview images of queried elements, highlighting results in the Revit viewport.
Advanced filtering — parameter-based queries with logic. "Find all fire-rated doors with opening width less than 36 inches."
Multi-document support — querying across multiple open Revit files and linked models.
Each of these builds on the same three-layer architecture. The threading model, error handling, and protocol layer are already in place.
For AEC Professionals
This isn't about replacing the architect's judgment or the engineer's expertise. It's about removing the friction between having a question and getting an answer. Every minute spent navigating UI to extract data is a minute not spent on design decisions.
The model contains the data. MCP makes it accessible through language. Claude makes it conversational.
For developers building AEC tools: this project demonstrates that complex desktop applications like Revit can be bridged to AI through open standards. The ExternalEvent threading pattern, the MCP protocol implementation, and the HTTP bridge architecture are patterns applicable to any desktop application with a single-threaded API constraint.
The project is open source on GitHub: revit-mcp-bridge. If you're working on similar integrations or have ideas for new tools, contributions are welcome.