Comment utiliser FreeCAD avec OpenCode et MCP

Introduction

FreeCAD est sans aucun doute l'une des applications de CAO paramétrique les plus puissantes qui existent. Pourtant, construire un modèle à partir de zéro peut parfois demander beaucoup de travail répétitif, de recherches de fonctionnalités en ligne et une tonne d'annulations... vraiment beaucoup !

Vous sélectionnez un atelier, créez un document, ajoutez des esquisses, appliquez des contraintes, créez des fonctions, inspectez l'arborescence et répétez le processus jusqu'à obtenir le bon résultat. Un peu pénible, non ?

Mais que diriez-vous de pouvoir décrire la pièce que vous souhaitez construire et de laisser un agent de programmation vous aider à la créer dans FreeCAD, comme vous le feriez avec du code ?

Ce serait vraiment génial, vous ne trouvez pas ?

Vous êtes donc au bon endroit, car c'est exactement ce que nous allons expliquer dans ce guide.

C'est l'idée derrière le serveur MCP de FreeCAD, un projet open source qui vous permet de connecter FreeCAD à un client d'IA compatible avec MCP afin de le contrôler directement à l'aide d'instructions en langage naturel !

L'objectif n'est pas de remplacer les connaissances en CAO ou d'accepter aveuglément la géométrie générée, mais de rendre l'interaction entre l'être humain et la machine plus conversationnelle et programmable. Nous pouvons demander à l'agent de créer un document, de générer une pièce simple, d'inspecter l'arborescence des objets, de modifier une dimension ou d'expliquer pourquoi une fonction a échoué, exactement comme nous le ferions avec une autre personne !

Ce qu'il nous faut

Commençons par dresser la liste de tout ce dont nous avons besoin pour ce petit projet :

La configuration la plus simple consiste à exécuter FreeCAD et OpenCode sur le même ordinateur. Ainsi, le serveur MCP peut utiliser la connexion locale par défaut et nous n'avons pas besoin d'exposer FreeCAD sur le réseau ni de modifier des configurations complexes.

Pourquoi FreeCAD ?

D'accord, mais pourquoi FreeCAD plutôt qu'une autre solution de CAO 3D populaire ?

J'ai choisi FreeCAD tout simplement parce qu'il est entièrement open source et gratuit, sans règles de licence obscures ni politiques étranges liées au nombre d'employés d'une entreprise. Vous voulez créer un projet 3D pour vous, votre famille ou une entreprise d'un million d'employés ? Aucun problème, aucune licence n'est nécessaire !

FreeCAD nous offre tous les outils nécessaires pour créer des pièces précises, des assemblages, des dessins techniques et bien plus, tout en conservant la possibilité de modifier les dimensions, les esquisses et les relations.

Contrairement à un simple programme de dessin, FreeCAD se souvient de la manière dont le modèle a été construit. Si nous modifions la longueur d'une esquisse, la position d'un trou ou l'épaisseur d'une fonction, le reste du modèle peut être mis à jour en fonction de ces relations au lieu de nous obliger à tout redessiner manuellement !

FreeCAD organise ses outils en différents ateliers. Nous pouvons donc choisir uniquement l'ensemble de fonctions qui correspond à la tâche à réaliser, ce qui rend le processus de création beaucoup plus simple et structuré.

Une autre fonctionnalité très intéressante de FreeCAD est que son comportement peut être étendu à l'aide d'extensions et de scripts. C'est donc un choix parfait pour expérimenter avec un agent de programmation utilisant l'IA tout en gardant le contrôle du design et des fichiers que nous créons.

Pourquoi OpenCode ?

Pour la partie agent, j'ai choisi OpenCode.

OpenCode est un agent de programmation très populaire et, comme il est open source, il s'accorde parfaitement avec FreeCAD.

Avec les modèles disponibles, il peut comprendre les demandes en langage naturel, planifier une suite d'actions et utiliser des outils connectés pour accomplir une tâche. Vous pouvez utiliser OpenCode avec votre LLM ou votre abonnement d'IA préféré, comme GitHub Copilot, ou le connecter à une plateforme externe basée sur une API comme OpenRouter.

Au lieu de considérer le terminal comme un endroit où nous devons saisir chaque commande à la perfection, nous pouvons décrire ce que nous voulons accomplir et laisser l'agent nous aider à choisir les étapes suivantes.

Dans notre cas précis, OpenCode nous offre une façon conversationnelle de demander à FreeCAD de créer des documents, de construire des modèles, d'inspecter des objets et d'expliquer clairement comment ces tâches ont été réalisées.

Nous pouvons décrire le résultat souhaité en termes simples, examiner le travail de l'agent et demander une modification précise lorsque quelque chose doit être corrigé. OpenCode peut également nous transmettre les réponses des outils, ce qui nous permet de lui demander de vérifier l'arborescence du document, de contrôler les dimensions ou de prendre une capture d'écran avant de prendre une nouvelle décision.

Comme il est open source, nous pouvons examiner son projet, le configurer localement et le connecter à des outils tels que le serveur MCP de FreeCAD au lieu de dépendre uniquement d'un flux de travail fermé et immuable.

Pourquoi utiliser un serveur MCP ?

Le Model Context Protocol, ou MCP en abrégé, offre à un client d'IA une manière standard de découvrir et d'appeler des outils externes capables de fournir du contexte aux appels LLM.

Au lieu de contrôler FreeCAD à l'aide de clics à l'écran et de mouvements de souris, OpenCode peut appeler directement les outils exposés par le serveur MCP de FreeCAD, ce qui lui permet de contrôler le logiciel de CAO via une API adaptée à l'IA.

Le projet FreeCAD MCP que nous allons utiliser dans ce guide fournit des outils pour des tâches telles que les suivantes :

L'agent dispose ainsi d'une boucle de rétroaction très utile. Il peut effectuer une modification, inspecter le résultat et adapter l'action suivante au lieu de simplement écrire du code que nous devrions coller manuellement. Plutôt pratique, non ?

1. Télécharger FreeCAD MCP

D'accord, la première chose à faire est de télécharger le dépôt officiel créé par l'incroyable neka-nat.

Pour cela, ouvrez un terminal, placez-vous dans le dossier de votre choix et exécutez la commande suivante :

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

Le dépôt contient à la fois le serveur MCP Python et l'extension FreeCAD. Conservez-le dans un emplacement stable, car OpenCode utilisera son chemin lorsqu'il démarrera le serveur.

Sous Windows, je vous conseille de le conserver dans votre dossier Documents. Vous pouvez par exemple utiliser :

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

Si vous utilisez un autre emplacement, ne vous inquiétez pas. Nous devrons simplement remplacer le chemin d'exemple dans la configuration OpenCode plus loin dans ce guide.

2. Installer l'extension FreeCAD

Le serveur MCP a également besoin d'une extension installée dans FreeCAD. Le dépôt officiel contient tout ce dont nous avons besoin dans le répertoire addon/FreeCADMCP.

Sous Windows, FreeCAD 1.1 utilise le répertoire d'extension spécifique à la version suivant :

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

Pour installer l'extension, ouvrez le dépôt cloné et copiez le dossier FreeCADMCP depuis addon.

Collez-le ensuite dans le dossier FreeCAD suivant. Créez le dossier Mod s'il n'existe pas encore :

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

En résumé, copiez le dossier suivant :

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

dans ce dossier :

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

Les anciennes versions de FreeCAD utilisent peut-être le dossier C:\Users\YourName\AppData\Roaming\FreeCAD\Mod pour les extensions. Utilisez le répertoire correspondant au dossier spécifique à la version créé par votre installation de FreeCAD.

Après avoir copié l'extension, redémarrez FreeCAD s'il était déjà ouvert. Le dépôt documente également les emplacements des extensions pour Linux et macOS si vous utilisez un autre système d'exploitation.

Sélectionner l'atelier MCP Addon

Après avoir redémarré FreeCAD, ouvrez le sélecteur d'ateliers et choisissez MCP Addon. Vous devriez maintenant voir la barre d'outils ou le menu FreeCAD MCP.

Cliquez sur Start RPC Server pour démarrer le pont local. Le serveur MCP lancé par OpenCode utilisera ce pont pour communiquer avec FreeCAD.

Le serveur RPC doit normalement être démarré à chaque ouverture de FreeCAD. Si vous souhaitez le démarrer automatiquement, ouvrez le menu FreeCAD MCP et activez Auto-Start Server. Le réglage est enregistré par l'extension et reste actif d'une session à l'autre.

3. Installer OpenCode

L'étape suivante consiste à installer OpenCode.

Nous pouvons installer OpenCode avec l'installateur officiel et la commande Bash suivante :

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

Si, comme moi, vous préférez utiliser npm, vous pouvez utiliser la commande suivante à la place :

$npm i -g opencode-ai

Une fois l'installation terminée, ouvrez un nouveau terminal afin que la commande opencode soit disponible dans votre PATH. Vérifions qu'elle fonctionne :

$opencode --version

Vous devrez également configurer un fournisseur d'IA avant qu'OpenCode puisse agir comme agent de programmation. S'il s'agit de votre première installation d'OpenCode, consultez la documentation OpenCode pour configurer le fournisseur.

4. Configurer OpenCode

OpenCode lit la configuration de son projet dans un fichier opencode.json ou opencode.jsonc. Nous pouvons placer ce fichier à la racine d'un projet ou utiliser la configuration globale d'OpenCode si nous voulons que FreeCAD soit disponible partout.

Sous Windows, le fichier de configuration globale se trouve généralement ici :

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

Si le répertoire ou le fichier n'existe pas encore, créez-le avant d'ajouter la configuration.

Créez ou modifiez maintenant la configuration OpenCode et ajoutez le serveur MCP de FreeCAD sous la clé mcp, comme indiqué ci-dessous :

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

Remplacez C:\\Users\\YourName\\Documents\\freecad-mcp par le chemin réel de votre copie. Les chemins JSON utilisent des barres obliques inverses échappées. Un chemin Windows tel que C:\Users\YourName\Documents\freecad-mcp doit donc être écrit C:\\Users\\YourName\\Documents\\freecad-mcp dans le fichier JSON.

5. Démarrer OpenCode

Avant de lancer OpenCode, vérifions que FreeCAD est ouvert, que l'atelier MCP Addon est sélectionné et que le serveur RPC fonctionne.

Si tout semble correct, démarrez OpenCode depuis le répertoire qui contient la configuration :

$opencode

OpenCode devrait détecter le serveur MCP freecad au démarrage. Si le serveur n'apparaît pas, vérifiez le chemin dans opencode.json, confirmez que uv est disponible dans votre PATH et consultez le statut du serveur MCP OpenCode.

Nous pouvons également demander à OpenCode s'il peut accéder au FreeCAD MCP avec une instruction simple :

Do you have access to the FreeCAD MCP?

Ne commencez pas par un projet de CAO complexe. Un petit test de connexion permet de déterminer beaucoup plus facilement si un problème ultérieur vient d'OpenCode, du serveur MCP ou de FreeCAD lui-même.

Si la réponse est positive, félicitations ! OpenCode est maintenant connecté au FreeCAD MCP.

6. Créer le premier projet

D'accord, continuons avec une demande un peu plus détaillée :

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

L'agent devrait appeler create_document, puis get_objects. Selon les réglages du serveur, la réponse peut également inclure une capture de la vue FreeCAD.

Si la demande aboutit, vous avez confirmé toute la chaîne de connexion :

Excellent ! À ce stade, enregistrez le document manuellement ou demandez à l'agent de l'enregistrer avec Python pour FreeCAD. Conserver ce premier document de test est utile pour résoudre les problèmes plus tard.

7. Créer une pièce paramétrique simple

Une fois la connexion fonctionnelle, nous pouvons demander à l'agent de créer un petit modèle avec des dimensions précises. Une plaque simple avec quatre trous est un bon premier projet, car sa géométrie est claire et facile à inspecter.

Nous pouvons par exemple utiliser une instruction comme celle-ci :

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'implémentation exacte dépend de l'agent. Il peut créer des primitives Part, utiliser une esquisse et un pad, ou exécuter du Python FreeCAD pour construire la forme. L'essentiel est d'indiquer clairement les dimensions, les contraintes, les attentes concernant les noms et les limites de sécurité.

Inspecter le résultat

Une fois le modèle créé, demandons à l'agent de l'inspecter au lieu de demander immédiatement une autre fonction :

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.

C'est ici que le flux de travail MCP devient plus utile qu'une génération de code en une seule étape. Nous pouvons comparer le rapport de l'agent avec l'arborescence FreeCAD et la vue, puis demander une correction ciblée.

Par exemple, si les trous ne sont pas au bon endroit, nous pouvons 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.

Formulez des demandes de modification précises. Demander à l'agent de « rendre le modèle plus joli » lui donne trop de liberté et rend le résultat plus difficile à vérifier.

8. Travailler avec Python pour FreeCAD

L'outil execute_code permet à l'agent d'exécuter du Python dans FreeCAD. C'est une fonctionnalité vraiment puissante, car FreeCAD expose une grande partie de ses fonctions de modélisation via Python. Cela signifie également que nous devons vérifier le code généré avant d'autoriser des modifications importantes.

Commençons par une demande d'exploration sans risque :

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.

Pour une tâche de modélisation contrôlée, demandez d'abord à l'agent d'expliquer les opérations prévues :

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

Cette étape supplémentaire est utile lorsque nous apprenons l'API ou travaillons sur un modèle qui contient un travail de conception important.

N'oubliez pas que les opérations FreeCAD peuvent avoir des dépendances. Supprimer ou modifier un objet peut affecter des esquisses, des pads, des découpes ou des fonctions en aval. Un modèle qui semble correct sur une capture d'écran peut tout de même contenir des relations paramétriques fragiles ou incorrectes.

Dépannage

En cas de problème, voici une courte liste de vérifications à suivre :

Le projet FreeCAD MCP avertit que les opérations GUI ne peuvent pas toujours être annulées de force en toute sécurité. Si une opération GUI reste bloquée, envoyer d'autres demandes GUI peut aggraver la situation. Vérifiez le statut RPC et redémarrez FreeCAD si nécessaire.

Si execute_code lève une exception lors de la création d'un objet FeaturePython, inspectez le nouvel objet avant d'essayer de le modifier ou de le supprimer. Un objet partiellement créé peut ne pas avoir le proxy attendu.

Conseils pratiques

Un agent de programmation utilisant l'IA est particulièrement utile lorsque nous le considérons comme un collaborateur compétent dont le travail doit être vérifié. Donnez-lui des exigences mesurables, demandez-lui d'inspecter son résultat et limitez les modifications afin de pouvoir les annuler facilement.

Pour les tâches répétitives, décrivez les dimensions et les contraintes plutôt que l'apparence visuelle uniquement. « Crée une plaque de 100 mm sur 60 mm avec quatre trous de 6 mm » est beaucoup plus utile que « crée une petite plaque de montage ».

Il est également conseillé d'enregistrer des versions de nos fichiers FreeCAD avant les modifications importantes. Les modèles paramétriques peuvent contenir des dépendances cachées et une modification apparemment mineure peut invalider une fonction ultérieure.

Enfin, n'oubliez pas qu'une CAO générée n'est pas automatiquement sûre à fabriquer. Vérifiez vous-même les unités, les tolérances, les épaisseurs de paroi, les dégagements des fixations, les hypothèses concernant les matériaux et les paramètres d'exportation. L'agent peut accélérer le processus de conception, mais la responsabilité technique reste entre les mains de la personne qui approuve le modèle.

Conclusion

Nous voici enfin arrivés au bout de cette aventure ! FreeCAD MCP permet de connecter une session FreeCAD en cours d'exécution à un agent compatible avec MCP. Avec OpenCode, nous pouvons décrire une tâche de modélisation en langage naturel, laisser l'agent créer ou modifier des objets FreeCAD, inspecter le résultat et poursuivre avec des instructions ciblées.

Voici un bref résumé de ce que nous avons fait :

Pour découvrir d'autres exemples et les dernières instructions d'installation, consultez le dépôt FreeCAD MCP et la documentation MCP d'OpenCode.

Si votre test de connexion a fonctionné et que l'agent a créé votre première pièce, félicitations ! Vous disposez maintenant d'un pont conversationnel entre OpenCode et FreeCAD et pouvez commencer à expérimenter avec vos propres modèles paramétriques !

Pensez à maintenir FreeCAD, le dépôt FreeCAD MCP, OpenCode et uv à jour afin que la configuration continue de fonctionner de manière fiable. Avant toute modification importante, enregistrez une copie de votre modèle et vérifiez toujours la géométrie générée avant de l'utiliser dans un vrai projet.

Si vous aimez les projets open source pratiques comme celui-ci, vous pouvez également consulter notre guide pour configurer Pi-hole et Mullvad sur un Raspberry Pi pour mettre en place une solution de confidentialité à l'échelle du réseau, ou notre guide pour utiliser l'application mobile Mullvad VPN lorsque vous souhaitez protéger des appareils individuels en déplacement !

Voilà, c'est tout pour aujourd'hui ! J'espère que ce guide vous a plu et que nous nous retrouverons bientôt !