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 | 繁體中文
Questa traduzione è stata realizzata con l'aiuto dell'IA. Il README in inglese è la fonte di riferimento; le correzioni sono benvenute tramite pull request (vedi CONTRIBUTING.md).
Interroga la tua IA sul modello Revit che hai aperto. Per impostazione predefinita, gli strumenti di scrittura restano bloccati finché non approvi un piano.
Server MCP open source e add-in nativo per Revit 2024 – 2027. Funziona con Claude, Codex e altri client MCP.
Per iniziare | Flussi di lavoro di esempio | Strumenti | Documentazione | Download
AEC Model Bridge è il server MCP open source per Revit che permette a Claude, Codex, Cursor e ad altri assistenti IA di leggere e modificare il modello Revit che hai aperto, con ogni modifica approvata prima da te. Unisce un server MCP in Python a un add-in Revit nativo: gli strumenti di sola lettura ispezionano subito il modello, mentre le modifiche al modello richiedono, per impostazione predefinita, un piano approvato. Vedi il flusso di approvazione.
La configurazione è documentata per Claude Desktop, VS Code con GitHub Copilot, Cursor e Codex. È un server MCP stdio standard, quindi dovrebbero funzionare anche altri client come Claude Code, Windsurf, Cline, Continue, Zed e Gemini CLI. Consulta la compatibilità per sapere cosa è documentato e cosa non è stato testato.
Lo stesso server include l'ispezione IFC, l'automazione di Rhino e Grasshopper e l'integrazione con Speckle. Lo stato delle integrazioni distingue i provider disponibili da quelli ancora in sviluppo.
Cronologia delle stelle
Flussi di lavoro di esempio
Per i coordinatori BIM: controllare la qualità del modello, esaminare gli elementi interessati, approvare una correzione dei parametri, poi verificare i risultati ed esportare un report. Questi esempi usano strumenti del catalogo attuale.
| Flusso di lavoro | Richiesta di esempio | Strumenti usati |
|---|---|---|
| Verifica del modello | "Mostra il documento attivo, elenca i suoi avvisi e trova gli elementi interessati." | revit_get_document_info, revit_get_warnings, revit_get_elements_by_type |
| Aggiornamento dei parametri | "Trova i muri al Level 02, mostra i loro valori di Comments e proponi un aggiornamento in blocco." | revit_get_elements_by_type, revit_get_element_parameters, revit_batch_set_parameters |
| Produzione degli elaborati | "Prepara un elenco di tavole (sheet) da questo CSV, poi proponi di creare le tavole e di posizionare le viste." | revit_batch_create_sheets_from_csv, revit_place_viewport_on_sheet |
| Verifica IFC | "Mostra i piani di questo file IFC, ispeziona le proprietà dei muri e segnala i problemi di validazione dello schema." | ifc_get_spatial_structure, ifc_get_properties, ifc_validate |
Per una prima prova in Revit, usa questo prompt:
Read the active model's warnings. Group them by description and show the
affected element IDs. Then suggest which issues to investigate first.
Poi prova con una correzione di parametro, sostituendo livello e valore con quelli del tuo progetto:
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.
Per le modifiche, l'assistente crea un piano con plan_actions; lo esamini nel pannello di Revit prima che execute_plan lo applichi. La verifica IFC funziona senza Revit.
I moduli di QA/QC e di report basati su snapshot richiedono uno snapshot salvato compatibile. L'attuale passaggio dello snapshot da Revit al modulo richiede che nome del file e workspace coincidano; omettendo snapshot_id possono essere restituiti dati di esempio generati. Per l'ispezione in tempo reale usa direttamente gli strumenti Revit indicati sopra. Correzioni previste e demo.
Avvio rapido
Installazione con un clic
I pulsanti richiedono solo uv e nessun'altra configurazione: il server usa ~/Documents/AEC Model Bridge come workspace, a meno che tu non ne imposti uno tuo. Per Claude Desktop, scarica il file .mcpb dall'ultima release e aprilo. Per lavorare con Revit in esecuzione servono comunque Revit e l'add-in; la modalità mock non richiede nulla.
Configurazione manuale
Per automatizzare Revit in tempo reale servono Windows, Revit 2024-2027 con licenza, Python 3.11 o successivo, uv e l'add-in di Revit (passaggi di installazione). Poi aggiungi questo al tuo claude_desktop_config.json (Codex, Cursor e VS Code usano gli stessi valori; le due variabili di directory sono facoltative e, per impostazione predefinita, puntano al workspace indicato sopra):
{
"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"
}
}
}
}
Vuoi prima dare un'occhiata agli strumenti, senza Revit? Imposta "MCP_REVIT_MODE": "mock". Il server si avvia ovunque, elenca ogni strumento con il suo schema e restituisce risposte predefinite senza toccare alcun modello. Un Dockerfile per la stessa modalità mock si trova nella radice del repository (docker build -t aec-model-bridge ., poi docker run -i --rm aec-model-bridge).
Usi VS Code? Il sorgente dell'estensione e i passaggi di installazione locale registrano il server MCP e mostrano lo stato della connessione a Revit. Non è stata pubblicata sul Marketplace.
Gli strumenti in sintesi
| Area | Strumenti | Cosa fanno |
|---|---|---|
| Revit | 103 | Leggere il modello, creare e modificare elementi, parametri, viste, tavole, abachi, esportazioni, condivisione del lavoro (worksharing) |
| Approvazione | 6 | Pianificare, rivedere, approvare, eseguire e annullare le modifiche al modello |
| Moduli | 34 | Ispezione degli snapshot, griglie di parametri, controlli QA/QC, ricette, report, selezioni |
| Rhino e Grasshopper | 19 | Geometria, layer, materiali, operazioni booleane |
| Speckle | 17 | Progetti, modelli, versioni, invio e ricezione |
| Navisworks | 15 | Albero del modello, punti di vista, verifiche di interferenza (in sviluppo) |
| IFC | 7 | Leggere file IFC senza Revit: struttura, proprietà, validazione |
| Grafo, snapshot, esportazioni, job | 18 | Audit del grafo semantico, differenze tra snapshot, esportazione SQLite, job in background |
Nella configurazione predefinita sono elencati 219 strumenti (contati dal server attuale in modalità mock). Gli strumenti Autodesk Data compaiono quando sono configurate le credenziali APS. Il riferimento degli strumenti li elenca tutti. Ogni strumento ha annotazioni MCP (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), così i client possono distinguere le letture dalle scritture.
Automazione avanzata di Revit
Oltre alle query sul modello e agli aggiornamenti dei parametri, gli strumenti Revit creano elementi edilizi, viste, tavole, abachi, etichette e quote, ed esportano file IFC, DWG, immagini e Navisworks. Consulta il riferimento degli strumenti per operazioni e input supportati.
Per ciò che il catalogo non copre, revit_invoke_method, revit_reflect_get e revit_reflect_set lavorano con i membri pubblici dell'API di Revit, e revit_execute_python esegue IronPython all'interno di Revit. Questi strumenti avanzati hanno gli stessi permessi del processo Revit. Usali solo con client MCP e prompt di cui ti fidi.
Come funziona
Il client MCP parla con un unico hub Python. L'hub invia ogni chiamata al provider che possiede lo strumento. I provider per le applicazioni desktop comunicano via localhost con un piccolo add-in all'interno di quell'applicazione.
Sorgente del diagramma: architecture.mmd. Rigenera le immagini con python scripts/render_diagrams.py.
I riquadri verde acqua funzionano oggi. I riquadri ambra tratteggiati sono in sviluppo. Le forme indaco sono dati e servizi esterni.
Come funziona l'approvazione
L'hub blocca qualsiasi chiamata a uno strumento che modifica il modello, a meno che non porti con sé un piano approvato. La modalità predefinita è required. L'IA propone un piano, tu lo esamini nel pannello laterale di Revit e l'add-in lo esegue nel thread principale di Revit, le azioni sui parametri e di modifica del modello ciascuna in una propria transazione con nome; salvataggio, sincronizzazione e script no, quindi Ctrl+Z non le copre.
Sorgente del diagramma: approval-flow.mmd. Rigenera le immagini con python scripts/render_diagrams.py.
Se un piano si rivela sbagliato, annullalo con Ctrl+Z in Revit. Ogni scrittura di parametro è una transazione con nome a sé, quindi un piano può richiedere più pressioni. Un annullamento in un solo passaggio per un intero piano è pianificato, non realizzato. Una seconda via è un piano di ripristino: l'assistente ne redige uno con plan_revert a partire dalla prova di un piano eseguito, e tu lo approvi come qualsiasi altro piano. rollback_plan è solo per le persone e non è né un pulsante né un comando, quindi non contarci. Nessuna di queste vie è ancora verificata in una sessione Revit reale (UNVERIFIED). Le operazioni che non si possono annullare, come la scrittura di file, non vengono annullate da nessuna di esse e non chiedono ancora una seconda conferma (pianificato). L'elenco Plans del pannello mostra solo i piani in sospeso; aec-model-bridge-approve show <plan_id> funziona per un piano in qualsiasi stato, mentre i pacchetti proofs/ esistono solo per i piani eseguiti (o tentati). Il ciclo di vita è descritto nell'ADR 0008.
Per le pipeline non presidiate puoi impostare MCP_REVIT_APPROVAL_MODE=auto. Questo disattiva il controllo da parte di una persona, quindi usalo solo in un ambiente controllato.
Versioni di Revit supportate
| Versione di Revit | Target dell'add-in | Strumenti di build |
|---|---|---|
| 2024 | .NET Framework 4.8 | .NET 8 SDK e .NET Framework 4.8 developer pack |
| 2025 | .NET 8 for Windows | .NET 8 SDK |
| 2026 | .NET 8 for Windows | .NET 8 SDK |
| 2027 | .NET 10 for Windows | .NET 10 SDK |
Servono inoltre Windows 10 o 11, Python 3.11 o successivo e un'installazione di Revit con licenza per la versione che usi. La modalità mock esegue il server senza Revit, utile per sviluppo e test.
Altre integrazioni
| Integrazione | Stato |
|---|---|
| Revit | Disponibile. Add-in nativo in C#. |
| IFC (IfcOpenShell) | Disponibile. Legge file IFC senza che Revit sia in esecuzione. |
| Rhino e Grasshopper | Disponibile. Si collega all'add-in di Rhino su localhost:3004. |
| Speckle | Disponibile. Richiede un client ID di Speckle nel tuo ambiente. |
| Navisworks Manage | In sviluppo. Il provider e i suoi strumenti sono registrati. L'add-in di Navisworks non è terminato. |
| Power BI | In sviluppo. Il provider e lo strumento esistono ma non sono registrati nell'hub. |
| Excel, Parquet e DuckDB | Pianificato. |
I nomi dei prodotti e i loghi appartengono ai rispettivi proprietari. Il banner li usa solo per mostrare con cosa funziona questo progetto.
Installare l'add-in di Revit
Il modo più semplice (Windows): scarica AECModelBridge-Setup-<version>.exe dall'ultima release, fai doppio clic, scegli le tue versioni di Revit e riavvia Revit. Installa l'add-in, il server Python incluso e, se spunti la casella, le impostazioni di Claude Desktop e VS Code, con un backup delle tue impostazioni attuali. Si disinstalla da Impostazioni di Windows. I passaggi seguenti servono per compilare dai sorgenti.
Devi installare due componenti: il server MCP in Python e l'add-in di Revit. L'automazione di Revit in tempo reale le richiede entrambe.
1. Installare il server 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. Installare l'add-in di Revit
Imposta la versione in modo che corrisponda alla tua installazione di Revit. Se Windows blocca gli script scaricati, fai clic con il tasto destro su ogni file .ps1, apri Proprietà e seleziona Sblocca prima di eseguirli.
$RevitVersion = Read-Host "Revit year (2024, 2025, 2026, or 2027)"
.\scripts\package.ps1 -RevitVersion $RevitVersion
.\scripts\install.ps1 -RevitVersion $RevitVersion
Il programma di installazione colloca i binari specifici di ogni versione in:
C:\ProgramData\AECModelBridge\bin\<year>
Il manifest dell'add-in viene installato per utente in:
%APPDATA%\Autodesk\Revit\Addins\<year>
Usa -AllUsers con install.ps1 per installare invece il manifest in C:\ProgramData\Autodesk\Revit\Addins\<year>.
Per preparare i binari di tutte le versioni supportate in un colpo solo:
.\scripts\package.ps1 -RevitVersion All
Ogni release di GitHub include un pacchetto già pronto per ogni anno di Revit, ad esempio aec-model-bridge-revit-2026-<version>.zip. Decomprimilo ed esegui .\install.ps1 -RevitVersion 2026 invece di compilare dai sorgenti. Per un installer Windows con doppio clic, scripts/build-installer.ps1 ne genera uno con Inno Setup. La guida completa, con la risoluzione dei problemi, è in docs/install.md.
Collegare Claude Desktop a Revit
Aggiungi il server alla configurazione del tuo client MCP. Per Claude Desktop è la sezione mcpServers di claude_desktop_config.json. Codex, Cursor, VS Code e altri client MCP usano gli stessi valori di command, args ed env nel proprio formato di configurazione.
Usa l'eseguibile Python del tuo ambiente virtuale e scegli una cartella di workspace a cui il server possa accedere:
{
"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"
}
}
}
}
Ometti MCP_REVIT_HOST_VERSION per puntare all'istanza di Revit aperta più recente. Impostala su un anno come 2024 o 2026 per vincolare una voce del client a quella versione di Revit. MCP_REVIT_BRIDGE_URL sostituisce l'endpoint nelle configurazioni avanzate.
Gli utenti di VS Code possono partire da .vscode/mcp.json. Gli utenti di Hermes Desktop possono partire da docs/examples/hermes-desktop.json dopo aver sostituito il percorso Python segnaposto. I client che supportano MCP Bundles possono installare il file .mcpb dall'ultima release. L'add-in di Revit resta necessario, perché il server comunica con l'applicazione desktop in esecuzione.
Verificare la connessione
Riavvia Revit dopo aver installato l'add-in, apri un modello ed esegui:
$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"
La risposta deve riportare healthy e la versione di Revit in esecuzione. In Revit cerca la scheda della barra multifunzione AEC Bridge. Il suo pannello Workflows contiene Open Panel, Health Check, Pending Actions e Reports. Il pannello Tools contiene Config, Help e About.
Sicurezza
- Il bridge di Revit è raggiungibile solo da localhost.
- Il server legge e scrive solo nelle cartelle indicate in
MCP_REVIT_ALLOWED_DIRECTORIES. - Gli strumenti che modificano il modello richiedono un piano approvato, a meno che tu non disattivi l'approvazione.
- Le chiamate agli strumenti vengono scritte in un registro di audit e i segreti vengono mascherati.
I dettagli sono in docs/security.md. Per segnalare una vulnerabilità, segui SECURITY.md.
FAQ
Che cos'è un server MCP per Revit?
Il Model Context Protocol (MCP) è uno standard aperto che permette agli assistenti IA di chiamare strumenti in altri software. Un server MCP per Revit pubblica le operazioni di Revit come strumenti. L'assistente sceglie gli strumenti e l'add-in li esegue dentro Revit.
Con quali assistenti IA funziona?
Con qualsiasi client MCP in grado di avviare un server stdio locale. Documentiamo Claude Desktop, VS Code con GitHub Copilot, Cursor e Codex, oltre ai client che leggono una configurazione mcpServers standard. Windsurf, Cline, Roo Code, Continue, Zed, Claude Code e Gemini CLI dovrebbero funzionare allo stesso modo, ma non sono stati testati. Vedi la compatibilità. La chat del pannello può anche usare una chiave API Anthropic o gli strumenti da riga di comando claude o codex, se installati. Vedi l'ADR 0012.
L'IA può modificare il mio modello senza chiedere?
Non nella modalità predefinita. Gli strumenti che modificano il modello sono bloccati finché un piano non viene approvato nel pannello di Revit. Gli strumenti di sola lettura funzionano senza approvazione. Se imposti MCP_REVIT_APPROVAL_MODE=auto, l'approvazione viene saltata.
Invia il mio modello al cloud?
Il server e l'add-in girano sul tuo computer e il bridge è raggiungibile solo da localhost. Ciò che vede l'assistente IA dipende dal client che usi: i risultati degli strumenti vanno al provider del modello di quel client. I provider rivolti al cloud, come Speckle, funzionano solo quando li configuri e ne chiami gli strumenti.
Funziona con i file IFC senza Revit?
Sì. Il provider IFC legge i file con IfcOpenShell. Può restituire metadati del file, struttura spaziale, proprietà degli elementi e bounding box, eseguire query per classe, GUID, nome o proprietà e validare lo schema. Non modifica i file IFC.
Posso usarlo senza Revit installato?
Puoi eseguire il server in modalità mock per sviluppo e test. Il lavoro in tempo reale sul modello richiede Revit 2024-2027 e l'add-in.
Release e versioni
AEC Model Bridge segue il Semantic Versioning. Le release sono etichettate vX.Y.Z su GitHub e un file VERSION nella radice contiene il numero di versione. Vedi docs/versioning.md per il processo di rilascio e CHANGELOG.md per le modifiche di ogni versione.
Sviluppo
# 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
La CI compila il server Python e i target dell'add-in per Revit 2024-2027. Leggi CONTRIBUTING.md prima di aprire una pull request.
Documentazione
- Guida all'installazione
- Riferimento degli strumenti
- Architettura
- Riferimento della configurazione
- Sicurezza
- Client MCP e registry
- Versioning e release
- Tutta la documentazione
- Come contribuire e Codice di condotta
- Collaboratori
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.
Progetto e licenza
Mantenuto da A. Sam Mohammad. LinkedIn | Issues
GPL-3.0-or-later con la Revit Linking Exception, oppure licenza commerciale.