Open-source Revit MCP server: let Claude and other AI assistants read and edit BIM models, with human approval on every change.
English | 简体中文 | Español | हिन्दी | العربية | Português (BR) | Русский | 日本語 | Deutsch | Français | Bahasa Indonesia | Türkçe | 한국어 | Tiếng Việt | Italiano | Polski | 繁體中文
تمت هذه الترجمة بمساعدة الذكاء الاصطناعي. المرجع الأساسي هو ملف README الإنجليزي، ونرحّب بالتصحيحات عبر pull request (راجع CONTRIBUTING.md).
اسأل الذكاء الاصطناعي عن نموذج Revit المفتوح لديك. افتراضيًا، تُحظر أدوات الكتابة حتى توافق على خطة.
خادم MCP مفتوح المصدر وإضافة أصلية لبرنامج Revit 2024 – 2027. يعمل مع Claude وCodex وعملاء MCP الآخرين.
ابدأ الآن | أمثلة على سير العمل | الأدوات | التوثيق | التنزيل
AEC Model Bridge هو خادم MCP مفتوح المصدر لبرنامج Revit، يتيح لـ Claude وCodex وCursor وغيرها من مساعدي الذكاء الاصطناعي قراءة نموذج Revit المفتوح لديك وتعديله، على أن توافق أنت أولًا على كل تغيير. يجمع بين خادم MCP مكتوب بلغة Python وإضافة Revit أصلية: تفحص الأدوات المخصصة للقراءة فقط النموذج فورًا، أما أي تغيير في النموذج فيتطلب افتراضيًا خطة معتمدة. اطّلع على آلية الموافقة.
إعداد الاتصال موثّق لـ Claude Desktop وVS Code مع GitHub Copilot وCursor وCodex. وبما أنه خادم MCP قياسي يعمل عبر stdio، فمن المتوقع أن تعمل معه عملاء أخرى مثل Claude Code وWindsurf وCline وContinue وZed وGemini CLI. راجع التوافق لمعرفة ما هو موثّق وما لم يُختبر بعد.
يتضمن الخادم نفسه فحص ملفات IFC وأتمتة Rhino وGrasshopper والتكامل مع Speckle. يبيّن حالة التكاملات المزوّدات المتاحة وتلك التي ما زالت قيد التطوير.
سجل النجوم
أمثلة على سير العمل
لمنسّقي BIM: افحص جودة النموذج، وراجع العناصر المتأثرة، ووافق على تصحيح المعاملات (parameters)، ثم تحقق من النتائج وصدّر تقريرًا. تستخدم هذه الأمثلة أدوات من الفهرس الحالي.
| سير العمل | مثال على الطلب | الأدوات المستخدمة |
|---|---|---|
| مراجعة النموذج | "اعرض المستند النشط، وأدرج تحذيراته، وابحث عن العناصر المتأثرة." | revit_get_document_info، revit_get_warnings، revit_get_elements_by_type |
| تحديث المعاملات | "ابحث عن الجدران في Level 02، واعرض قيم Comments الخاصة بها، واقترح تحديثًا دفعيًا." | revit_get_elements_by_type، revit_get_element_parameters، revit_batch_set_parameters |
| إنتاج المخططات | "جهّز قائمة لوحات (sheets) من ملف CSV هذا، ثم اقترح إنشاء اللوحات ووضع المناظير (views)." | revit_batch_create_sheets_from_csv، revit_place_viewport_on_sheet |
| مراجعة IFC | "اعرض طوابق ملف IFC هذا، وافحص خصائص الجدران، وأبلغ عن مشكلات التحقق من المخطط." | ifc_get_spatial_structure، ifc_get_properties، ifc_validate |
لتجربة أولى داخل Revit، جرّب ما يلي:
Read the active model's warnings. Group them by description and show the
affected element IDs. Then suggest which issues to investigate first.
ثم جرّب تصحيح معامل، مع استبدال المستوى والقيمة بما يناسب مشروعك:
Find walls on Level 02 and show their current Comments values. Propose setting
Comments to "Coordination reviewed" for the elements I choose. After I approve
the plan in Revit, apply it and read the values back to confirm the result.
في التعديلات، ينشئ المساعد خطة باستخدام plan_actions؛ وتراجعها أنت في لوحة Revit قبل أن يطبّقها execute_plan. مراجعة IFC تعمل دون Revit.
تتطلب وحدات QA/QC والتقارير القائمة على اللقطات (snapshots) لقطة محفوظة متوافقة. ويحتاج تمرير اللقطة حاليًا من Revit إلى الوحدة إلى تطابق اسم الملف ومساحة العمل؛ وقد يؤدي حذف snapshot_id إلى إرجاع بيانات نموذجية مولَّدة. استخدم أدوات Revit المباشرة أعلاه للفحص الحي. الإصلاحات المخططة والعرض التجريبي.
البدء السريع
التثبيت بنقرة واحدة
تحتاج الأزرار إلى uv فقط دون أي إعداد آخر: يستخدم الخادم المجلد ~/Documents/AEC Model Bridge كمساحة عمل ما لم تحدد مساحتك الخاصة. بالنسبة إلى Claude Desktop، نزّل ملف .mcpb من أحدث إصدار وافتحه. ما زال العمل الحي مع Revit يتطلب Revit والإضافة؛ أما الوضع التجريبي (mock) فلا يحتاج إلى شيء.
الإعداد اليدوي
للأتمتة الحية في Revit تحتاج إلى Windows، ونسخة مرخّصة من Revit من 2024 إلى 2027، وPython 3.11 أو أحدث، وuv، وإضافة Revit (خطوات التثبيت). ثم أضف ما يلي إلى ملف claude_desktop_config.json (يستخدم Codex وCursor وVS Code القيم نفسها؛ ومتغيرا المجلدين اختياريان ويشيران افتراضيًا إلى مساحة العمل المذكورة أعلاه):
{
"mcpServers": {
"aec-model-bridge": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Sam-AEC/aec-model-bridge#subdirectory=packages/mcp-server-revit",
"aec-model-bridge"
],
"env": {
"MCP_REVIT_MODE": "bridge",
"MCP_REVIT_WORKSPACE_DIR": "C:\\RevitProjects",
"MCP_REVIT_ALLOWED_DIRECTORIES": "C:\\RevitProjects"
}
}
}
}
هل تريد الاطلاع على الأدوات أولًا دون Revit؟ اضبط "MCP_REVIT_MODE": "mock". عندئذٍ يعمل الخادم في أي مكان، ويسرد كل الأدوات مع مخططاتها، ويعيد ردودًا جاهزة دون أن يلمس أي نموذج. يوجد ملف Dockerfile للوضع التجريبي نفسه في جذر المستودع (docker build -t aec-model-bridge . ثم docker run -i --rm aec-model-bridge).
تستخدم VS Code؟ يسجّل مصدر الامتداد وخطوات التثبيت المحلي خادم MCP ويعرض حالة الاتصال بـ Revit. لم يُنشر الامتداد في Marketplace.
نظرة سريعة على الأدوات
| المجال | الأدوات | ماذا تفعل |
|---|---|---|
| Revit | 103 | قراءة النموذج، وإنشاء العناصر والمعاملات والمناظير واللوحات والجداول وتحريرها، والتصدير، والعمل المشترك (worksharing) |
| الموافقة | 6 | تخطيط تغييرات النموذج ومراجعتها واعتمادها وتنفيذها والتراجع عنها |
| الوحدات | 34 | فحص اللقطات، وشبكات المعاملات، وفحوص QA/QC، والوصفات، والتقارير، والتحديدات |
| Rhino وGrasshopper | 19 | الهندسة، والطبقات، والخامات، والعمليات المنطقية (boolean) |
| Speckle | 17 | المشاريع، والنماذج، والإصدارات، والإرسال والاستقبال |
| Navisworks | 15 | شجرة النموذج، ونقاط الرؤية، واختبارات التعارض (قيد التطوير) |
| IFC | 7 | قراءة ملفات IFC دون Revit: البنية، والخصائص، والتحقق |
| الرسم البياني، واللقطات، والتصدير، والمهام | 18 | تدقيق الرسم البياني الدلالي، وفروق اللقطات، والتصدير إلى SQLite، والمهام الخلفية |
تُدرج 219 أداة في الإعداد الافتراضي (عُدّت من الخادم الحالي في الوضع التجريبي mock). تظهر أدوات Autodesk Data عند ضبط بيانات اعتماد APS. يسرد مرجع الأدوات كل أداة. تحمل كل أداة تعليقات MCP التوضيحية (readOnlyHint وdestructiveHint وidempotentHint وopenWorldHint)، ليتمكّن العملاء من التمييز بين القراءة والكتابة.
أتمتة Revit المتقدمة
إلى جانب استعلامات النموذج وتحديثات المعاملات، تنشئ أدوات Revit عناصر المباني والمناظير واللوحات والجداول والوسوم والأبعاد، وتصدّر ملفات IFC وDWG والصور وملفات Navisworks. راجع مرجع الأدوات للاطلاع على العمليات والمدخلات المدعومة.
لما لا يغطيه فهرس الأدوات، تعمل revit_invoke_method وrevit_reflect_get وrevit_reflect_set مع أعضاء واجهة Revit API العامة، وتشغّل revit_execute_python شيفرة IronPython داخل Revit. لهذه الأدوات المتقدمة الصلاحيات نفسها التي لعملية Revit. لا تستخدمها إلا مع عملاء MCP وprompts تثق بها.
كيف يعمل
يتحدث عميل MCP مع موزّع (hub) واحد مكتوب بـ Python. يرسل الموزّع كل استدعاء إلى المزوّد الذي يملك الأداة. وتتحدث مزوّدات تطبيقات سطح المكتب عبر localhost مع إضافة صغيرة داخل ذلك التطبيق.
مصدر المخطط: architecture.mmd. أعد توليد الصور بالأمر python scripts/render_diagrams.py.
المربعات ذات اللون الأخضر المزرق تعمل اليوم. المربعات ذات الحدود المتقطعة بلون العنبر قيد التطوير. أما الأشكال النيلية فتمثّل البيانات والخدمات الخارجية.
كيف تعمل الموافقة
يوقف الموزّع أي استدعاء لأداة يغيّر النموذج ما لم يحمل خطة معتمدة. الوضع الافتراضي هو required. يقترح الذكاء الاصطناعي خطة، وتراجعها أنت في اللوحة الجانبية في Revit، ثم تنفّذها الإضافة على الخيط الرئيسي (main thread) في Revit وتنفّذ إجراءات تعديل المعاملات (parameters) والنموذج كلًّا ضمن معاملة (transaction) مسمّاة مستقلة؛ أما إجراءات الحفظ والمزامنة والسكربتات فلا، لذا لا يشملها Ctrl+Z.
مصدر المخطط: approval-flow.mmd. أعد توليد الصور بالأمر python scripts/render_diagrams.py.
إذا تبيّن أن خطة ما خاطئة، فتراجع عنها بـ Ctrl+Z في Revit. كل كتابة لمعامل هي معاملة مسمّاة مستقلة، لذا قد تحتاج خطة واحدة إلى عدة ضغطات. التراجع بخطوة واحدة عن خطة كاملة مخطَّط له ولم يُبنَ بعد. يعيد الطريق الثاني هو خطة تراجع: يصيغ المساعد واحدة بالأداة plan_revert انطلاقًا من إثبات خطة نُفّذت، وتوافق عليها كأي خطة أخرى. rollback_plan مخصص للأشخاص فقط وليس زرًا ولا أمرًا، فلا تعتمد عليه. لم يُتحقَّق من أيٍّ من هذه المسارات في جلسة Revit حقيقية بعد (UNVERIFIED). أما العمليات التي لا يمكن عكسها، مثل كتابة الملفات، فلا يتراجع عنها أيٌّ منها، ولا تطلب تأكيدًا ثانيًا بعد (مخطَّط له). تعرض قائمة الخطط في اللوحة الخطط المعلّقة فقط؛ ويعمل الأمر aec-model-bridge-approve show <plan_id> مع خطة في أي حالة، بينما لا توجد حزم proofs/ إلا للخطط التي نُفّذت (أو جرت محاولة تنفيذها). دورة الحياة موضحة في ADR 0008.
في خطوط المعالجة الآلية غير المراقَبة يمكنك ضبط MCP_REVIT_APPROVAL_MODE=auto. يؤدي ذلك إلى إيقاف المراجعة البشرية، لذا استخدمه في بيئة خاضعة للتحكم فقط.
إصدارات Revit المدعومة
| إصدار Revit | هدف الإضافة | أدوات البناء |
|---|---|---|
| 2024 | .NET Framework 4.8 | .NET 8 SDK وحزمة المطوّر لـ .NET Framework 4.8 |
| 2025 | .NET 8 for Windows | .NET 8 SDK |
| 2026 | .NET 8 for Windows | .NET 8 SDK |
| 2027 | .NET 10 for Windows | .NET 10 SDK |
تحتاج أيضًا إلى Windows 10 أو 11، وPython 3.11 أو أحدث، ونسخة Revit مرخّصة للإصدار الذي تستخدمه. يشغّل الوضع التجريبي (mock) الخادم دون Revit، وهو مفيد للتطوير والاختبار.
تكاملات أخرى
| التكامل | الحالة |
|---|---|
| Revit | متاح. إضافة أصلية بلغة C#. |
| IFC (IfcOpenShell) | متاح. يقرأ ملفات IFC دون الحاجة إلى تشغيل Revit. |
| Rhino وGrasshopper | متاح. يتصل بإضافة Rhino على localhost:3004. |
| Speckle | متاح. يحتاج إلى معرّف عميل Speckle في بيئتك. |
| Navisworks Manage | قيد التطوير. المزوّد وأدواته مسجّلان، لكن إضافة Navisworks لم تكتمل. |
| Power BI | قيد التطوير. المزوّد والأداة موجودان لكنهما غير مسجّلين في الموزّع. |
| Excel وParquet وDuckDB | مخطط له. |
أسماء المنتجات والشعارات مملوكة لأصحابها. تُستخدم في اللافتة العلوية فقط لبيان ما يعمل معه هذا المشروع.
تثبيت إضافة Revit
الأسهل (Windows): نزّل AECModelBridge-Setup-<version>.exe من أحدث إصدار، وانقر عليه نقرًا مزدوجًا، واختر إصدارات Revit لديك، ثم أعد تشغيل Revit. يثبّت الإضافة وخادم Python المرفق، وإذا حددت الخيار فيثبّت أيضًا إعدادات Claude Desktop وVS Code مع نسخة احتياطية من إعداداتك الحالية. يمكنك إلغاء التثبيت من إعدادات Windows. الخطوات أدناه مخصصة للبناء من المصدر.
عليك تثبيت جزأين: خادم MCP بلغة Python وإضافة Revit. تحتاج الأتمتة الحية في Revit إلى كليهما.
1. تثبيت خادم MCP
git clone https://github.com/Sam-AEC/aec-model-bridge.git
cd aec-model-bridge
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e packages/mcp-server-revit
2. تثبيت إضافة Revit
اضبط الإصدار ليطابق تثبيت Revit لديك. إذا حظر Windows السكربتات التي نزّلتها، فانقر بزر الفأرة الأيمن على كل ملف .ps1، وافتح Properties، واختر Unblock قبل تشغيلها.
$RevitVersion = Read-Host "Revit year (2024, 2025, 2026, or 2027)"
.\scripts\package.ps1 -RevitVersion $RevitVersion
.\scripts\install.ps1 -RevitVersion $RevitVersion
يضع المثبّت الملفات التنفيذية الخاصة بكل إصدار في:
C:\ProgramData\AECModelBridge\bin\<year>
يُثبَّت ملف بيان الإضافة (manifest) لكل مستخدم في:
%APPDATA%\Autodesk\Revit\Addins\<year>
استخدم -AllUsers مع install.ps1 لتثبيت ملف البيان في C:\ProgramData\Autodesk\Revit\Addins\<year> بدلًا من ذلك.
لتجهيز الملفات التنفيذية لكل الإصدارات المدعومة دفعة واحدة:
.\scripts\package.ps1 -RevitVersion All
يتضمن كل إصدار على GitHub حزمة جاهزة لكل سنة من Revit، مثل aec-model-bridge-revit-2026-<version>.zip. فك ضغطها ثم شغّل .\install.ps1 -RevitVersion 2026 بدلًا من البناء من المصدر. ولإنشاء مثبّت Windows بنقرة مزدوجة، يبنيه السكربت scripts/build-installer.ps1 باستخدام Inno Setup. الدليل الكامل، مع استكشاف الأخطاء وإصلاحها، في docs/install.md.
ربط Claude Desktop بـ Revit
أضف الخادم إلى إعدادات عميل MCP لديك. في Claude Desktop هو قسم mcpServers في claude_desktop_config.json. يستخدم Codex وCursor وVS Code وغيرها من عملاء MCP قيم command وargs وenv نفسها بصيغة الإعداد الخاصة بكل منها.
استخدم ملف Python التنفيذي من بيئتك الافتراضية، واختر مجلد مساحة عمل يُسمح للخادم بالوصول إليه:
{
"mcpServers": {
"aec-model-bridge": {
"command": "C:\\path\\to\\aec-model-bridge\\.venv\\Scripts\\python.exe",
"args": ["-m", "revit_mcp_server.mcp_server"],
"env": {
"MCP_REVIT_MODE": "bridge",
"MCP_REVIT_WORKSPACE_DIR": "C:\\RevitProjects",
"MCP_REVIT_ALLOWED_DIRECTORIES": "C:\\RevitProjects"
}
},
"aec-model-bridge-revit-2026": {
"command": "C:\\path\\to\\aec-model-bridge\\.venv\\Scripts\\python.exe",
"args": ["-m", "revit_mcp_server.mcp_server"],
"env": {
"MCP_REVIT_MODE": "bridge",
"MCP_REVIT_HOST_VERSION": "2026",
"MCP_REVIT_WORKSPACE_DIR": "C:\\RevitProjects",
"MCP_REVIT_ALLOWED_DIRECTORIES": "C:\\RevitProjects"
}
}
}
}
احذف MCP_REVIT_HOST_VERSION لاستهداف أحدث نسخة Revit مفتوحة. واضبطه على سنة مثل 2024 أو 2026 لتثبيت إدخال العميل على ذلك الإصدار من Revit. يتجاوز MCP_REVIT_BRIDGE_URL نقطة الاتصال في الإعدادات المتقدمة.
يمكن لمستخدمي VS Code البدء من .vscode/mcp.json. ويمكن لمستخدمي Hermes Desktop البدء من docs/examples/hermes-desktop.json بعد استبدال مسار Python النموذجي. ويمكن للعملاء الذين يدعمون MCP Bundles تثبيت ملف .mcpb من أحدث إصدار. وتبقى إضافة Revit مطلوبة لأن الخادم يتحدث مع تطبيق سطح المكتب العامل.
التحقق من الاتصال
أعد تشغيل Revit بعد تثبيت الإضافة، وافتح نموذجًا، ثم نفّذ:
$registry = Get-ChildItem "$env:LOCALAPPDATA\AECModelBridge\registry\revit-*.json" | Select-Object -First 1
$switch = Get-Content $registry.FullName -Raw | ConvertFrom-Json
Invoke-RestMethod "$($switch.endpoint)/health"
يجب أن يُظهر الرد healthy وإصدار Revit العامل. في Revit، ابحث عن علامة التبويب AEC Bridge في الشريط. تضم لوحة Workflows الأوامر Open Panel وHealth Check وPending Actions وReports. وتضم لوحة Tools الأوامر Config وHelp وAbout.
الأمان
- يستمع جسر Revit على localhost فقط.
- يقرأ الخادم ويكتب داخل المجلدات المذكورة في
MCP_REVIT_ALLOWED_DIRECTORIESفقط. - تحتاج الأدوات التي تغيّر النموذج إلى خطة معتمدة ما لم توقف الموافقة.
- تُسجَّل استدعاءات الأدوات في سجل تدقيق، وتُخفى القيم السرية.
التفاصيل في docs/security.md. للإبلاغ عن ثغرة أمنية، اتبع SECURITY.md.
الأسئلة الشائعة
ما هو خادم MCP لبرنامج Revit؟
بروتوكول Model Context Protocol (MCP) معيار مفتوح يتيح لمساعدي الذكاء الاصطناعي استدعاء أدوات في برامج أخرى. ينشر خادم MCP لبرنامج Revit عمليات Revit على هيئة أدوات. يختار المساعد الأدوات، وتنفّذها الإضافة داخل Revit.
ما مساعدو الذكاء الاصطناعي الذين يعملون معه؟
أي عميل MCP قادر على تشغيل خادم stdio محلي. نوثّق إعداد Claude Desktop وVS Code مع GitHub Copilot وCursor وCodex، والعملاء الذين يقرؤون إعداد mcpServers القياسي. ويُتوقع أن تعمل Windsurf وCline وRoo Code وContinue وZed وClaude Code وGemini CLI بالطريقة نفسها، لكنها لم تُختبر. راجع التوافق. ويمكن لمحادثة اللوحة أيضًا استخدام مفتاح Anthropic API أو أداتي سطر الأوامر claude أو codex إذا كانتا مثبّتتين. راجع ADR 0012.
هل يستطيع الذكاء الاصطناعي تغيير نموذجي دون أن يسأل؟
ليس في الوضع الافتراضي. تُحجب الأدوات التي تغيّر النموذج حتى تُعتمد خطة في لوحة Revit. وتعمل الأدوات للقراءة فقط دون موافقة. وإذا ضبطت MCP_REVIT_APPROVAL_MODE=auto فستُتجاوز الموافقة.
هل يرسل نموذجي إلى السحابة؟
يعمل الخادم والإضافة على جهازك، ويستمع الجسر على localhost. وما يراه مساعد الذكاء الاصطناعي يعتمد على العميل الذي تستخدمه: تذهب نتائج الأدوات إلى مزوّد النموذج لدى ذلك العميل. أما المزوّدات المرتبطة بالسحابة، مثل Speckle، فلا تعمل إلا عند ضبطها واستدعاء أدواتها.
هل يعمل مع ملفات IFC دون Revit؟
نعم. يقرأ مزوّد IFC الملفات باستخدام IfcOpenShell. يمكنه إرجاع بيانات الملف الوصفية والبنية المكانية وخصائص العناصر والصناديق المحيطة (bounding boxes)، وتنفيذ استعلامات بحسب الفئة أو GUID أو الاسم أو الخاصية، والتحقق من المخطط. ولا يحرّر ملفات IFC.
هل يمكنني استخدامه دون تثبيت Revit؟
يمكنك تشغيل الخادم في الوضع التجريبي (mock) للتطوير والاختبار. أما العمل الحي على النموذج فيحتاج إلى Revit من 2024 إلى 2027 والإضافة.
الإصدارات والنسخ
يتبع AEC Model Bridge نظام الإصدارات الدلالي. تُوسَم الإصدارات على GitHub بالصيغة vX.Y.Z، ويحتوي ملف VERSION في الجذر على رقم الإصدار. راجع docs/versioning.md لعملية الإصدار، وCHANGELOG.md لما تغيّر في كل إصدار.
التطوير
# Python tests
python -m pytest packages/mcp-server-revit/tests
# Build one Revit version, for example 2026
.\scripts\build-addin.ps1 -RevitVersion 2026 -Configuration Release
# Build all supported versions
.\scripts\package.ps1 -RevitVersion All
يبني CI خادم Python وأهداف الإضافة لإصدارات Revit من 2024 إلى 2027. راجع CONTRIBUTING.md قبل فتح pull request.
التوثيق
- دليل التثبيت
- مرجع الأدوات
- البنية المعمارية
- مرجع الإعدادات
- الأمان
- عملاء MCP والسجل
- الإصدارات والنسخ
- كل التوثيق
- دليل المساهمة و مدونة السلوك
- المساهمون
Built with
AEC Model Bridge stands on open-source work. It is independent and is not affiliated with or endorsed by any project named here.
- Model Context Protocol Python SDK (MIT) for the MCP server
- IfcOpenShell (LGPL-3.0-or-later) for IFC files
- specklepy (Apache-2.0) for Speckle
- pydantic, httpx, NetworkX, openpyxl and PyYAML (MIT or BSD)
- Anthropic Python SDK (MIT) for the built-in agent chat
- Serilog, IronPython and Microsoft WebView2 in the Revit add-in
- Autodesk Revit and Navisworks and McNeel Rhino are separate products that you license yourself. This project does not include their code.
Licence texts and the full list of packages are in THIRD_PARTY_NOTICES.md. Licences were read from package metadata; rows that could not be verified are marked as such.
المشروع والترخيص
يتولى صيانته A. Sam Mohammad. LinkedIn | Issues
GPL-3.0-or-later مع استثناء الربط بـ Revit (Revit Linking Exception)، أو ترخيص تجاري.