Come usare FreeCAD con OpenCode e MCP

Introduzione

FreeCAD è senza dubbio una delle applicazioni CAD parametriche più potenti disponibili, ma a volte costruire un modello da zero può richiedere molto lavoro ripetitivo, la ricerca online delle funzionalità e una valanga di annullamenti... davvero tanti!

Selezioni un ambiente di lavoro, crei un documento, aggiungi schizzi, applichi vincoli, crei funzioni, controlli l'albero e ripeti il processo finché il risultato non è corretto. Un po' scomodo, no?

Ma cosa succederebbe se potessi descrivere il pezzo che vuoi costruire e lasciare che un coding agent ti aiuti a crearlo dentro FreeCAD, proprio come fai con il codice?

Sarebbe davvero fantastico, non credi?

Allora sei decisamente nel posto giusto, perché è esattamente ciò che spiegheremo in questa guida.

Questa è l'idea alla base del server MCP di FreeCAD, un progetto open source che permette di collegare FreeCAD a un client AI compatibile con MCP, così possiamo controllarlo direttamente tramite prompt in linguaggio naturale!

L'obiettivo non è sostituire le conoscenze CAD o accettare alla cieca la geometria generata, ma rendere l'interazione tra persona e macchina più conversazionale e programmabile. Possiamo chiedere all'agente di creare un documento, generare un componente semplice, ispezionare l'albero degli oggetti, modificare una dimensione o spiegare perché una funzione non è riuscita, proprio come faremmo con un essere umano!

Cosa ci serve

Per prima cosa, iniziamo elencando tutto ciò che ci serve per questo piccolo progetto:

La configurazione più semplice per questo progetto consiste nell'eseguire FreeCAD e OpenCode sulla stessa macchina. In questo modo, il server MCP può usare la connessione locale predefinita e non dobbiamo esporre FreeCAD alla rete o modificare configurazioni complesse.

Perché FreeCAD

Va bene, ma perché FreeCAD invece di un'altra soluzione CAD 3D popolare?

Ho scelto FreeCAD semplicemente perché è completamente open source e gratuito, senza regole di licenza oscure o strane politiche basate sul numero di dipendenti di un'azienda. Vuoi creare un progetto 3D per te, la tua famiglia o la tua azienda con un milione di dipendenti? Nessun problema, non serve alcuna licenza!

FreeCAD ci offre tutti gli strumenti necessari per creare componenti precisi, assiemi, disegni tecnici e molto altro, mantenendo modificabili dimensioni, schizzi e relazioni.

A differenza di un semplice programma di disegno, FreeCAD ricorda come è stato costruito il modello. Se cambiamo la lunghezza di uno schizzo, la posizione di un foro o lo spessore di una funzione, il resto del modello può aggiornarsi in base a quelle relazioni invece di costringerci a ridisegnare tutto manualmente!

FreeCAD organizza i suoi strumenti in diversi ambienti di lavoro, così possiamo scegliere solo l'insieme di funzioni adatto al compito da svolgere, rendendo il processo di creazione molto più semplice e ordinato.

Un'altra funzionalità davvero interessante di FreeCAD è che il suo comportamento può essere esteso tramite addon e script. È quindi la scelta perfetta per sperimentare con un coding agent AI mantenendo comunque il controllo sul design e sui file che creiamo.

Perché OpenCode

Per la parte relativa all'agente, ho deciso di usare OpenCode.

OpenCode è un coding agent molto popolare e, vista la sua natura open source, si abbina perfettamente a FreeCAD.

Con i modelli disponibili, può comprendere richieste in linguaggio naturale, pianificare una sequenza di azioni e usare strumenti collegati per aiutare a completare un'attività. Puoi usare OpenCode con il tuo LLM o abbonamento AI preferito, come GitHub Copilot, oppure collegarlo a una piattaforma esterna basata su API come OpenRouter.

Invece di considerare il terminale come un luogo in cui dobbiamo digitare ogni comando alla perfezione, possiamo descrivere ciò che vogliamo ottenere e lasciare che l'agente ci aiuti a scegliere i passaggi successivi.

Nel nostro caso specifico, OpenCode ci offre un modo conversazionale per chiedere a FreeCAD di creare documenti, costruire modelli, ispezionare oggetti e spiegare chiaramente come ha raggiunto quegli obiettivi.

Possiamo descrivere in linguaggio semplice il risultato che vogliamo, poi verificare il lavoro dell'agente e chiedere una modifica precisa quando qualcosa deve essere corretto. OpenCode può anche restituirci le risposte degli strumenti, permettendoci di chiedergli di controllare l'albero del documento, verificare le dimensioni o acquisire uno screenshot prima di prendere un'altra decisione.

Essendo open source, possiamo esaminare il suo progetto, configurarlo localmente e collegarlo a strumenti come il server FreeCAD MCP invece di affidarci soltanto a un flusso di lavoro chiuso e immutabile.

Perché usare un server MCP?

Il Model Context Protocol, o MCP in breve, offre a un client AI un modo standard per scoprire e chiamare strumenti esterni che possono fornire contesto alle chiamate LLM.

Invece di controllare FreeCAD tramite clic sullo schermo e movimenti del mouse, OpenCode può chiamare direttamente gli strumenti esposti dal server MCP di FreeCAD, permettendogli di controllare il software CAD attraverso un'API adatta all'AI.

Il progetto FreeCAD MCP che useremo in questa guida fornisce strumenti per attività come queste:

Questo fornisce all'agente un utile ciclo di feedback. Può apportare una modifica, ispezionare il risultato e adattare l'azione successiva invece di limitarsi a scrivere codice che dovremmo incollare manualmente. Piuttosto utile, vero?

1. Scaricare FreeCAD MCP

Bene, la prima cosa da fare è scaricare il repository ufficiale creato dall'incredibile neka-nat.

Per farlo, apri un terminale, spostati nella directory che preferisci ed esegui il comando seguente:

$git clone https://github.com/neka-nat/freecad-mcp.git

Il repository contiene sia il server MCP Python sia l'addon FreeCAD. Mantieni il repository in una posizione stabile, perché OpenCode userà il suo percorso quando avvierà il server.

Su Windows, ti consiglio di conservarlo nella cartella Documenti. Per esempio, puoi usare:

C:\Users\YourName\Documents\freecad-mcp

Se usi una posizione diversa, non preoccuparti. Dovremo semplicemente sostituire il percorso di esempio nella configurazione di OpenCode più avanti in questa guida.

2. Installare l'addon FreeCAD

Il server MCP ha bisogno anche di un addon installato in FreeCAD. Il repository ufficiale contiene tutto ciò che ci serve nella directory addon/FreeCADMCP.

Su Windows, FreeCAD 1.1 usa la seguente directory per gli addon specifica della versione:

C:\Users\YourName\AppData\Roaming\FreeCAD\v1-1\Mod\FreeCADMCP

Per installare l'addon, apri il repository clonato e copia la cartella FreeCADMCP da addon.

Incollala poi nella seguente cartella di FreeCAD. Crea la cartella Mod se non esiste ancora:

C:\Users\YourName\AppData\Roaming\FreeCAD\v1-1\Mod

In breve, copia la cartella seguente:

C:\Users\YourName\Documents\freecad-mcp\addon\FreeCADMCP

in questa cartella:

C:\Users\YourName\AppData\Roaming\FreeCAD\v1-1\Mod

Le versioni precedenti di FreeCAD potrebbero usare la cartella C:\Users\YourName\AppData\Roaming\FreeCAD\Mod per gli addon. Usa la directory che corrisponde alla cartella specifica della versione creata dalla tua installazione di FreeCAD.

Dopo aver copiato l'addon, riavvia FreeCAD se era già aperto. Il repository documenta anche le posizioni degli addon per Linux e macOS, nel caso tu stia usando un altro sistema operativo.

Selezionare l'ambiente di lavoro MCP Addon

Dopo aver riavviato FreeCAD, apri il selettore degli ambienti di lavoro e scegli MCP Addon. A questo punto dovresti vedere la barra degli strumenti o il menu FreeCAD MCP.

Fai clic su Start RPC Server per avviare il bridge locale. Il server MCP avviato da OpenCode userà questo bridge per comunicare con FreeCAD.

Il server RPC normalmente deve essere avviato ogni volta che FreeCAD viene aperto. Se vuoi avviarlo automaticamente, apri il menu FreeCAD MCP e abilita Auto-Start Server. L'impostazione viene salvata dall'addon e rimane attiva tra una sessione e l'altra.

3. Installare OpenCode

Il passaggio successivo consiste nell'installare OpenCode.

Possiamo installare OpenCode usando l'installer ufficiale con il seguente comando Bash:

$curl -fsSL https://opencode.ai/install | bash

Se, come me, preferisci usare npm, puoi usare invece il comando seguente:

$npm i -g opencode-ai

Al termine dell'installazione, apri un nuovo terminale in modo che il comando opencode sia disponibile nel tuo PATH. Controlliamo che funzioni:

$opencode --version

Dovrai anche configurare un provider AI prima che OpenCode possa agire come coding agent. Se questa è la tua prima installazione di OpenCode, segui la documentazione di OpenCode per configurare il provider.

4. Configurare OpenCode

OpenCode legge la configurazione del progetto da un file opencode.json o opencode.jsonc. Possiamo collocare questo file nella radice di un progetto oppure usare la configurazione globale di OpenCode se vogliamo che FreeCAD sia disponibile ovunque.

Su Windows, il file di configurazione globale si trova di solito qui:

C:\Users\YourName\.config\opencode\opencode.json

Se la directory o il file non esistono ancora, creali prima di aggiungere la configurazione.

Ora crea o modifica la configurazione di OpenCode e aggiungi il server MCP di FreeCAD sotto la chiave mcp, come mostrato qui sotto:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "freecad": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "C:\\Users\\YourName\\Documents\\freecad-mcp",
        "run",
        "freecad-mcp"
      ],
      "enabled": true
    }
  }
}

Sostituisci C:\\Users\\YourName\\Documents\\freecad-mcp con il percorso effettivo del tuo clone. I percorsi JSON usano barre rovesciate con escape, quindi un percorso Windows come C:\Users\YourName\Documents\freecad-mcp deve essere scritto come C:\\Users\\YourName\\Documents\\freecad-mcp all'interno del file JSON.

5. Avviare OpenCode

Prima di avviare OpenCode, assicuriamoci che FreeCAD sia aperto, che l'ambiente di lavoro MCP Addon sia selezionato e che il server RPC sia in esecuzione.

Se sembra tutto corretto, avvia OpenCode dalla directory che contiene la configurazione:

$opencode

OpenCode dovrebbe rilevare il server MCP freecad durante l'avvio. Se il server non compare, controlla il percorso in opencode.json, verifica che uv sia disponibile nel tuo PATH e controlla lo stato del server MCP di OpenCode.

Possiamo anche chiedere a OpenCode se riesce ad accedere a FreeCAD MCP con un prompt semplice:

Do you have access to the FreeCAD MCP?

Non iniziare con un progetto CAD complesso. Un piccolo test di connettività rende molto più facile capire se un problema successivo dipende da OpenCode, dal server MCP o da FreeCAD stesso.

Se la risposta è positiva, congratulazioni! OpenCode è ora connesso correttamente a FreeCAD MCP.

6. Creare il primo progetto

Bene, continuiamo con una richiesta un po' più dettagliata:

Use the freecad MCP server to create a new document named AgentTest, then list the objects in the document.

L'agente dovrebbe chiamare create_document e poi get_objects. A seconda delle impostazioni del server, la risposta potrebbe includere anche uno screenshot della vista di FreeCAD.

Se la richiesta va a buon fine, hai verificato l'intera catena di connessione:

Ottimo! A questo punto, salva manualmente il documento oppure chiedi all'agente di salvarlo usando Python per FreeCAD. Conservare questo primo documento di test è utile per risolvere eventuali problemi in seguito.

7. Creare un componente parametrico semplice

Quando la connessione funziona, possiamo chiedere all'agente di creare un piccolo modello con dimensioni esplicite. Una piastra semplice con quattro fori è un buon primo progetto, perché ha una geometria chiara ed è facile da ispezionare.

Per esempio, possiamo usare un prompt come questo:

Use the freecad MCP tools to create a new document containing a parametric rectangular plate.

Requirements:
- The plate should be 100 mm long, 60 mm wide, and 8 mm thick.
- Add four through-holes with a diameter of 6 mm.
- Place the holes symmetrically, 10 mm from the nearest two edges.
- Use meaningful object names.
- Recompute the document and report the objects and final dimensions.
- Do not overwrite any existing document.

L'implementazione esatta dipende dall'agente. Potrebbe creare primitive Part, usare uno schizzo e un pad, oppure eseguire Python per FreeCAD per costruire la forma. La cosa importante è indicare chiaramente dimensioni, vincoli, aspettative sui nomi e limiti di sicurezza.

Ispezionare il risultato

Dopo aver creato il modello, chiediamo all'agente di ispezionarlo invece di richiedere subito un'altra funzione:

Inspect the current FreeCAD document with the freecad MCP tools. List every object, its type, its dimensions, and any visible errors. Take an isometric view screenshot if available.

È qui che il flusso di lavoro MCP diventa più utile della generazione di codice in un unico passaggio. Possiamo confrontare il resoconto dell'agente con l'albero di FreeCAD e la vista, poi chiedere una correzione mirata.

Per esempio, se i fori non si trovano nella posizione corretta, possiamo dire:

The plate looks correct, but the holes are not symmetric around the center. Inspect the model and move only the hole locations so the four hole centers are 10 mm from the corresponding edges. Preserve the plate thickness and hole diameter.

Usa richieste di modifica precise. Chiedere all'agente di "rendere il modello più bello" gli lascia troppa libertà e rende il risultato più difficile da verificare.

8. Lavorare con Python per FreeCAD

Lo strumento execute_code permette all'agente di eseguire Python dentro FreeCAD. È una funzionalità davvero potente, perché FreeCAD espone gran parte delle sue funzioni di modellazione tramite Python, ma significa anche che dovremmo controllare il codice generato prima di consentirgli di apportare modifiche importanti.

Iniziamo con una richiesta esplorativa sicura:

Use execute_code only to inspect the active document. Return the document name and a list of object names and types. Do not create, delete, or modify anything.

Per un'attività di modellazione controllata, chiedi prima all'agente di spiegare le operazioni previste:

Before executing code, describe the FreeCAD objects and operations you plan to use to create the plate. Wait for confirmation before modifying the document.

Questo passaggio aggiuntivo è utile quando stiamo imparando l'API o lavorando con un modello che contiene un lavoro di progettazione importante.

Ricorda che le operazioni di FreeCAD possono avere dipendenze. Eliminare o modificare un oggetto può influire su schizzi, pad, tagli o funzioni successive. Un modello che sembra corretto in uno screenshot potrebbe comunque contenere relazioni parametriche fragili o errate.

Risoluzione dei problemi

Quando qualcosa non funziona, ecco una breve checklist da seguire:

Il progetto FreeCAD MCP avverte che le operazioni GUI non possono sempre essere annullate forzatamente in modo sicuro. Se un'operazione GUI si blocca, inviare altre richieste GUI può peggiorare la situazione. Controlla lo stato RPC e riavvia FreeCAD quando necessario.

Se execute_code genera un'eccezione durante la creazione di un oggetto FeaturePython, ispeziona il nuovo oggetto prima di provare a modificarlo o eliminarlo. Un oggetto creato solo parzialmente potrebbe non avere il proxy previsto.

Consigli pratici

Un coding agent AI è più utile quando lo consideriamo un collaboratore capace il cui lavoro deve essere verificato. Forniscigli requisiti misurabili, chiedigli di ispezionare il risultato e mantieni le modifiche abbastanza piccole da poter essere annullate.

Per il lavoro ripetitivo, descrivi dimensioni e vincoli invece di limitarti all'aspetto visivo. "Crea una piastra di 100 mm per 60 mm con quattro fori da 6 mm" è molto più utile di "crea una piccola piastra di montaggio".

È inoltre buona abitudine salvare versioni dei nostri file FreeCAD prima di modifiche più ampie. I modelli parametrici possono contenere dipendenze nascoste e una modifica apparentemente piccola può invalidare una funzione successiva.

Infine, ricorda che il CAD generato non è automaticamente sicuro da produrre. Controlla personalmente unità, tolleranze, spessori delle pareti, spazi per i dispositivi di fissaggio, ipotesi sui materiali e impostazioni di esportazione. L'agente può velocizzare il processo di progettazione, ma la responsabilità ingegneristica resta della persona che approva il modello.

Conclusione

Siamo finalmente arrivati alla fine di questo viaggio! FreeCAD MCP permette di collegare una sessione FreeCAD in esecuzione a un agente compatibile con MCP. Con OpenCode, possiamo descrivere un'attività di modellazione in linguaggio naturale, lasciare che l'agente crei o modifichi oggetti FreeCAD, ispezionare il risultato e procedere con istruzioni mirate.

Ecco un breve riepilogo di ciò che abbiamo fatto:

Per altri esempi e per le informazioni di installazione più recenti, consulta il repository FreeCAD MCP e la documentazione MCP di OpenCode.

Se il test di connessione ha funzionato e l'agente ha creato il tuo primo componente, congratulazioni! Ora hai un bridge conversazionale tra OpenCode e FreeCAD e puoi iniziare a sperimentare con i tuoi modelli parametrici!

Ricordati di mantenere aggiornati FreeCAD, il repository FreeCAD MCP, OpenCode e uv, così la configurazione continuerà a funzionare in modo affidabile. Prima di apportare modifiche importanti, salva una copia del modello e controlla sempre la geometria generata prima di usarla in un progetto reale.

Se ti piacciono i progetti open source pratici come questo, puoi anche consultare la nostra guida per configurare Pi-hole e Mullvad su un Raspberry Pi per una soluzione di privacy a livello di rete, oppure la nostra guida per usare l'app mobile Mullvad VPN quando vuoi proteggere i singoli dispositivi mentre sei fuori casa!

Ecco tutto per oggi! Spero che questa guida ti sia piaciuta e spero di rivederti presto in un altro articolo!