Bim Ai Agent

🤖 BIM AI Agent – Revit × Claude (MCP)

---

🇬🇧 English Documentation

📌 Project Overview

BIM AI Agent is a professional and safe bridge between Generative AI (Claude) and Autodesk Revit.

The project demonstrates how AI can analyze, query, and suggest actions on a BIM model without directly controlling Revit or violating Revit API constraints.

Key Idea: AI prepares the command, Revit executes it safely.

The system enables:

Asking natural language questions about a Revit model (Query)

Triggering controlled and user‑approved changes inside Revit (Action)

This architecture is fully local, stable, and Revit‑API‑compliant, and intentionally avoids:

Background threads inside Revit

Socket listeners or live servers in the Revit process

Direct AI‑to‑Revit execution

All Revit operations are executed only through pyRevit and require explicit user interaction, ensuring safety, transparency, and compliance with Revit best practices.

---

🎯 Project Objective

Bridge the gap between Generative AI and BIM software by enabling:

• Natural language queries on a Revit model
• Controlled, user-approved actions inside Revit
• A live, demonstrable AI–BIM workflow

This implementation satisfies:

✅ Query (e.g. count walls)

✅ Action (e.g. rename views)

✅ Live demo capability

✅ Revit API safety

---

🧠 System Architecture

Claude Desktop (LLM)
        │
        ▼
MCP Server (mcp_server.py)
        │
        ▼
Flask API (simple-flask-server.py)
        │   (writes command.json)
        ▼
User clicks AI_Bridge button
        │
        ▼
Revit + pyRevit (AI_Bridge.pushbutton)
        │   (executes Revit API)
        ▼
result.json
        │
        ▼
Claude reads final result

Why This Architecture?

• Revit API must run on the UI thread

• Background listeners and sockets are unsafe

• User‑triggered execution is required

• This design strictly follows Revit API best practices and professional BIM workflows.

---

🧩 System Components

1️⃣ Claude (AI)

• Interprets natural language requests
• Decides what should be done
• Calls MCP tools only
• ❌ No direct access to Revit

2️⃣ MCP Server

• Exposes tools to Claude
• Handles AI-to-backend communication

3️⃣ Flask Server

• Lightweight local backend
• Writes command.json
• Reads result.json
• Contains no Revit logic

4️⃣ File-Based IPC

• command.json: AI → Revit instructions
• result.json: Revit → AI execution results

5️⃣ pyRevit Bridge

• Runs inside Revit
• Reads commands
• Executes them using Revit API transactions
• Writes results
• Triggered manually by the user

6️⃣ Autodesk Revit

• The only component allowed to modify the model
• All changes occur inside safe transactions

---

🛠️ Available Commands

The following commands are exposed through the MCP server and can be invoked by the LLM to interact safely with Autodesk Revit. All modification commands follow a human-in-the-loop approach and require explicit user confirmation inside Revit before execution.

📊 Information & Queries

These commands do not modify the Revit model and are safe to run at any time.

ping Checks whether the MCP server is running and reachable. Useful for validating that the AI–Revit bridge is active.

get_wall_count Returns the total number of wall elements in the current Revit project.

ai_suggestions Requests an AI-based analysis of the model. The analysis is executed inside Revit after user confirmation and may return design observations or potential improvement notes. (An empty result indicates that no issues were detected or the model is too simple for analysis.)

get_last_result Retrieves the result of the most recently executed operation. This command is intended for programmatic feedback and verification rather than direct user interaction.

✏️ Model Modifications

These commands do not execute immediately. Each request is queued and requires the user to press the AI_Bridge button inside Revit and approve the action.

rename_views Renames Revit views by replacing an existing name prefix with a new one. This allows batch renaming of views in a controlled and predictable manner.

Example: Rename views starting with Level → Arc Level

flip_doors Safely attempts to flip the orientation of door elements. The system checks Revit API capabilities and skips doors that cannot be flipped to avoid errors or unintended behavior.

modify_parameter Modifies a specific parameter of a given element. Requires:

Element ID

Parameter name

New value

The operation is executed only after user confirmation inside Revit.

↩️ Revert & Recovery

revert_last Reverts the last successful modification operation, when supported. This provides a basic rollback mechanism for safe experimentation.

🔐 Safety Model

The AI never modifies the Revit model directly

All changes are:

• Requested by the AI

• Queued through the bridge

• Explicitly reviewed and confirmed by the user inside Revit

• This design prioritizes transparency, control, and model integrity over blind automation.

---

🔐 Design & Safety Philosophy

• User-in-the-loop execution
• Explicit approval for every action
• No hidden automation

> This approach mirrors professional workflows such as Git pull requests or CI/CD approvals.

---

📁 Project Structure

BIM_AI_Agent/
│
├── command.json # Temporary command file (created at runtime)
├── result.json # Result written by Revit execution
├── ai_server/
│   ├── command_writer.py # Writes AI commands to command.json
│   ├── simple-flask-server.py # Flask API (AI → file bridge)
│   └── mcp_server.py # MCP server used by Claude Desktop
└── revit/
    └── KaydaTools.extension/
        └── MyScripts.tab/
            ├── Utils.panel/
            ├── CountWalls.pushbutton/
            │ └── script.py
            ├── AI_Bridge.pushbutton/
            └── script.py

---

⚙️ Requirements

Software

• Autodesk Revit 2025
• pyRevit (installed and loaded)
• Python 3.10+ (for Flask + MCP)
• Claude Desktop (with MCP enabled)

Python Packages

pip install flask requests mcp

---

🚀 How to Run

1. Start Flask server

``bash cd BIM_AI_Agent\ai_server python simple-flask-server.py `` This server:

• Receives AI requests
• Writes command.json

1. Start MCP server

``bash cd BIM_AI_Agent\ai_server python mcp_server.py `` ⚠️ Do not type anything in this terminal. The MCP server is driven by Claude, not manually.

1. Open Claude Desktop (MCP enabled)

• Enable MCP tools
• Ensure MCP status = connected

1. Open Revit and reload pyRevit

• Open your project
• Reload pyRevit (once)
• Ask Claude for an action
• Press Bridge Button in Revit
• Ask Claude to read last result

---

🧠 Key Takeaway

> The AI is an intelligent assistant, not a decision-maker. > Execution authority always remains inside Revit and under human control.

💡 Note

⚠️ This project uses a local project root path. Please update PROJECT_ROOT in the Revit bridge script to match your local directory structure.

---

📺 Demo

🎥 A short demo video is available on LinkedIn (see post).

---

AR الشرح باللغة العربية

📌 فكرة المشروع

مشروع BIM AI Agent بيربط بين الذكاء الاصطناعي (Claude) و برنامج Revit بطريقة آمنة ومهنية، من غير ما يدي الـ AI أي صلاحية مباشرة للتعديل على الموديل.

الفكرة الأساسية:

• الـ AI يفهم طلب المستخدم
• يحوّل الطلب لأمر منظم
• الأمر يتكتب في ملف command.json
• Revit فقط هو اللي ينفّذ التعديل بعد موافقة المستخدم

> الفكرة المحورية: > الـ AI يقترح، وRevit ينفّذ بأمان.

---

🧠 ليه التصميم ده؟

• Revit API لازم يشتغل على UI Thread
• أي تشغيل في الخلفية خطر وغير آمن
• لازم تدخل بشري صريح في التنفيذ

وده التزام مباشر بقواعد Revit الاحترافية.

---

🧩 مكونات النظام

• Claude: يفهم ويقترح فقط
• Flask + MCP: طبقة وسيطة للاتصال
• ملفات JSON: وسيلة تواصل آمنة
• Bridge داخل Revit: تنفيذ حقيقي

---

🔐 فلسفة الأمان

• لا تنفيذ تلقائي
• لا تعديل بدون موافقة المستخدم
• التحكم دايمًا في إيد المهندس

---

✅ استخدامات مناسبة

• عدّ العناصر
• تنظيم أسماء الـ Views
• فحص جودة الموديل
• تقارير QA / QC

---

🚫 استخدامات غير مسموحة

• حذف عناصر تلقائيًا
• تعديل Geometry مباشر
• تحكم AI كامل في الموديل

---

🏁 الخلاصة

> الـ AI هنا مساعد ذكي، مش بديل عن المهندس. > التنفيذ الحقيقي بيتم داخل Revit وبموافقة المستخدم.

---

👤 Author

Ziad Amr Said Architecture • Frontend • BIM Automation • AI Integration

Built as part of an academic BIM course and independent experimentation. ---

📄 License

Educational / Research Use Only

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Ziad-Amr1
• Source: Ziad-Amr1/bim-ai-agent
• License: MIT

Install and usage instructions live in the source repository linked above.