Serena MCP donne à Claude Code des outils au niveau des symboles, et avec eux un véritable accès en écriture. Découvrez ce que peut faire l’outil shell, ce que coûtent en tokens les définitions d’outils, les commandes de configuration exactes et un déploiement en lecture seule qui protège votre dépôt.
Serena MCP est sûr à utiliser si vous le traitez comme tout outil capable de modifier votre code, car c’est exactement ce qu’il est. Le serveur tourne sur votre propre machine, le code source est public, et dans le contexte claude-code son outil shell est désactivé. Les vraies questions sont plus précises : que peut-il écrire sur le disque, ce qu’il envoie à l’extérieur, et combien de tokens consomme-t-il avant que vous ayez tapé le moindre prompt ? Cet article répond aux trois avec des commandes exactes, des noms de configuration et un ordre de déploiement que vous pouvez suivre dès aujourd’hui.
Un mot sur les sources. Les commandes et réglages ci-dessous proviennent du dépôt de Serena et de sa page de configuration client. Les chiffres de tokens viennent d’un wrapper tiers et d’une analyse de sécurité, que j’indique comme tels. Mesurez votre propre configuration avant de vous fier à un chiffre, le mien compris.
Serena, développé par Oraios, est un serveur MCP qui fournit à un agent de code des outils de type IDE. Au lieu de lire des fichiers entiers et de faire correspondre du texte, l’agent demande des symboles : classes, fonctions, méthodes et les endroits qui les référencent. Le dépôt liste des outils de recherche (trouver un symbole, aperçu des symboles, trouver les symboles référençant), l’édition symbolique (remplacer le corps d’un symbole, insérer avant ou après un symbole), la recherche par expressions régulières, les opérations sur les fichiers, l’exécution shell et un système de mémoire persistante. La prise en charge couvre plus de 40 langages grâce aux serveurs de langage.
Qui en tire profit ? Toute personne qui travaille sur un dépôt trop volumineux pour tenir dans un seul prompt : backends multi-modules, monorepos, applications anciennes où un renommage touche trente fichiers. Si votre projet se résume à quelques scripts, les outils classiques de Claude Code suffisent déjà, et ajouter un serveur ne fait surtout qu’augmenter la surface d’attaque. Adaptez l’outil à la taille du problème avant de vous demander s’il est sûr.
Un agent classique trouve une fonction en recherchant du texte, puis lit les fichiers environnants pour être sûr d’avoir la bonne. Serena interroge plutôt un serveur de langage, de sorte que la réponse est la définition elle-même, et non un tas de fichiers.
| Tâche | Outils de fichiers classiques | Outils Serena |
|---|---|---|
| Trouver une fonction | Rechercher du texte, lire des fichiers entiers | Trouver un symbole renvoie la définition |
| Voir qui l’appelle | Chercher et deviner | Trouver les symboles référençant |
| Modifier une méthode | Réécrire un bloc de texte | Remplacer le corps du symbole |
| S’orienter dans un fichier | Lire le fichier complet | Aperçu des symboles |
Claude Code lance Serena comme processus local, et les serveurs de langage tournent eux aussi en local. Serena n’est pas un service hébergé, et d’après la documentation publique, il n’existe pas de cloud Serena qui reçoive votre dépôt. Un point mérite d’être dit clairement : tout ce que renvoie un outil Serena atterrit dans le contexte de Claude, et ce contexte est envoyé à l’API du modèle comme tout autre résultat d’outil. Serena ne rend pas une session plus privée. Il rend les lectures plus petites et plus précises.
Pour la plupart des développeurs qui travaillent sur leurs propres dépôts, oui, sous conditions. Les risques sont ordinaires, et chacun dispose d’un contrôle que vous pouvez configurer en quelques minutes.
Partez du modèle de menace. Vous ne craignez pas qu’un inconnu s’introduise dans Serena. Vous craignez trois choses plus discrètes : que l’agent modifie des fichiers que vous n’aviez pas prévu de toucher, que l’agent exécute une commande que vous n’aviez pas prévue, et qu’un texte présent dans un fichier pousse l’agent à faire l’une ou l’autre. Ce dernier point est l’injection de prompt, et il concerne tout outil qui lit du contenu non fiable. Un dépôt cloné, une dépendance téléchargée ou un ticket collé peuvent contenir une phrase destinée au modèle plutôt qu’à vous. Une liste d’outils courte et une demande de confirmation pour les écritures forment la meilleure défense, car elles limitent ce qu’une instruction détournée peut atteindre.
| Domaine | Risque | Contrôle |
|---|---|---|
| Écritures de fichiers | Les modifications de symboles changent les fichiers sur le disque | read_only: true, un arbre git propre, relecture des différences |
| Shell | execute_shell_command exécute des commandes arbitraires | Exclu dans le contexte claude-code, plus excluded_tools |
| Télémétrie | Remontée anonyme d’usage | SERENA_USAGE_REPORTING=false |
| Chaîne d’approvisionnement | Exécution directe depuis une URL git | Installer le paquet ou épingler une étiquette |
| Injection de prompt | Un texte dans le dépôt peut donner des instructions à l’agent | Demandes de confirmation, liste d’outils réduite |
| Licence | Code de l’application sous GPL-3.0-or-later | Le lire avant toute redistribution |
Le code de l’application Serena est sous GPL-3.0-or-later, et la couche SolidLSP incluse est sous MIT. Un code ouvert signifie que vous pouvez lire exactement ce qui tourne sur votre machine, ce qui constitue une vraie garantie de sécurité. Exécuter un outil GPL sur votre dépôt ne modifie pas la licence de ce dépôt. La licence devient importante lorsque vous modifiez Serena et le distribuez à d’autres personnes, et à ce moment-là, mieux vaut consulter un juriste plutôt qu’un blog.
L’outil le plus sensible de l’ensemble est execute_shell_command. Une analyse de sécurité consacrée à Serena le qualifie de capacité la plus dangereuse, avec la suppression accidentelle de fichiers, la fuite d’identifiants et la dégradation de la configuration système comme modes de défaillance, et recommande de le réserver aux environnements CI plutôt qu’au travail local.
Le contexte claude-code le retire déjà. Ce contexte exclut six outils : create_text_file, read_file, execute_shell_command, find_file, list_dir et search_for_pattern. La raison n’a rien de paranoïaque. Claude Code dispose de ses propres outils de fichiers et de shell, donc Serena s’efface sur ces points et conserve le travail sur les symboles.
💡 Exclure l’outil shell de Serena ne retire pas la puissance shell de la session. L’outil Bash de Claude Code reste disponible, mais il passe par les demandes de confirmation de Claude Code, et c’est là que vous voulez que cette décision se prenne.
Serena documente une option de désactivation de la remontée anonyme d’usage : définissez SERENA_USAGE_REPORTING=false dans l’environnement qui lance le serveur. Les serveurs de langage sont des programmes distincts, et selon le langage, l’un d’eux peut devoir être téléchargé la première fois que vous l’utilisez. Attendez-vous à un peu d’activité réseau lors d’un premier lancement dans un nouveau langage, et vérifiez le journal de votre pare-feu si votre environnement est strict.
Serena consomme des tokens de deux façons. Le coût fixe correspond aux définitions d’outils chargées dans chaque session. Le coût variable correspond à ce que les outils renvoient pendant votre travail. Le premier est prévisible, le second dépend de votre façon de travailler.
Le projet wrapper serena-slim estime que le Serena d’origine charge 29 outils représentant environ 23 878 tokens dans Claude Code, et que sa version regroupée, avec 18 opérations, ramène ce total à environ 11 874 tokens. Il s’agit d’un chiffre fourni par l’éditeur d’un wrapper tiers, pas d’une mesure de votre installation. Dans le contexte claude-code, six outils sont déjà exclus, donc votre total est probablement inférieur à celui de la version d’origine.
Mesurez-le vous-même. Lancez /context dans Claude Code avant d’ajouter le serveur, puis à nouveau après, et comparez la ligne des outils MCP. Cette seule comparaison vaut mieux que n’importe quelle estimation de cet article.
Pour comprendre pourquoi le coût fixe compte, voici un calcul, pas une mesure. Supposons que les définitions pèsent 12 000 tokens et que vous ouvriez 20 sessions par jour. Cela fait 240 000 tokens de surcharge avant même qu’une question soit posée. Si vous réduisez la charge de moitié, vous économisez encore autant chaque jour, que Serena soit utile ou non dans cette session.
Le coût variable se répartit en trois postes :
no-onboarding et no-memories désactivent cela lorsque vous voulez une session allégée.Les contextes sont choisis au démarrage et ne peuvent pas changer en cours de session. Le contexte par défaut est desktop-app, qui est prévu pour un client différent de Claude Code. Sans --context claude-code, attendez-vous à des outils de fichiers qui font double emploi avec ceux de Claude Code, à un outil shell et à une charge de définitions plus lourde, le tout à la fois. Tapez /mcp après la configuration et comparez la liste des outils aux six exclusions ci-dessus. Un seul indicateur règle en même temps le coût en tokens et l’exposition en matière de sécurité.
Claude Code peut aussi différer le chargement des définitions d’outils MCP et les charger à la demande plutôt qu’au démarrage. Une analyse de configuration active cette option avec ENABLE_TOOL_SEARCH=true ; vérifiez les notes de version de votre Claude Code, car l’interrupteur peut différer. Un wrapper allégé ajoute un paquet tiers de plus entre vous et votre code. Pesez-le face aux tokens économisés, car l’économie ne vaut que si vous faites confiance à cette couche supplémentaire.
L’ensemble de la procédure prend quelques minutes. uv est le seul prérequis.
uv tool install -p 3.13 serena-agent
serena init
Serena propose aussi un raccourci, serena setup claude-code, pour la même tâche. Les commandes manuelles ci-dessous vous montrent exactement à quoi vous consentez, c’est pourquoi je les préfère la première fois.
Pour un seul projet, lancez cette commande depuis le dossier du projet :
claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"
Pour tous les projets de la machine, la forme globale est :
claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd
Je recommande la commande par projet. Claude Code la stocke par défaut dans la portée locale, donc elle ne s’applique qu’à ce projet, alors que la forme globale active Serena dans n’importe quel dossier que vous ouvrez, si bien qu’une session lancée par erreur dans le mauvais répertoire obtient les mêmes outils d’édition. Vérifiez le résultat avec claude mcp list, ou tapez /mcp dans Claude Code. Si le serveur met du temps à démarrer, augmentez le délai avec export MCP_TIMEOUT=60000.
💡 Sous Windows, exécutez ces commandes dans PowerShell et remplacez
"$(pwd)"par"$PWD"si votre shell se plaint. Évitez les guillemets superflus dans le chemin du projet, car un mauvais chemin amène Serena à activer le mauvais dossier.
La documentation de Serena avertit que les mises à jour récentes de Claude Code et des modèles ont réduit la capacité de l’agent à suivre les instructions concernant les outils de Serena, et que les longues sessions peuvent s’en écarter. La solution consiste à lancer Claude Code avec une surcharge du prompt système :
claude --system-prompt="$(serena prompts print-cc-system-prompt-override)"
La documentation recommande aussi fortement des crochets de rappel dans .claude/settings.json, avec quatre commandes : remind, activate, cleanup et auto-approve. Lisez ce que fait auto-approve avant de l’intégrer. Tout ce qui approuve les appels d’outils à votre place réduit le nombre de moments où vous pouvez dire non.
Procédez dans cet ordre. Chaque étape vous fournit les éléments nécessaires à la suivante.
Serena lit ses réglages dans un fichier global, ~/.serena/serena_config.yml (sous Windows, %USERPROFILE%\.serena\serena_config.yml), et dans un project.yml qui le remplace pour un projet donné. Ouvrez l’un ou l’autre avec serena config edit. Pour les premières sessions, définissez ceci dans le fichier du projet :
read_only: true
Dans ce mode, Serena peut lire les fichiers, inspecter la structure, rechercher des symboles et construire des index, mais il ne peut pas écrire. Les lectures sont là où les outils de symboles font économiser des tokens, donc vous perdez peu à commencer ainsi, et vous ne renoncez à rien que vous ne puissiez activer plus tard.
Serena propose un tableau de bord local, généralement à l’adresse http://localhost:24282/dashboard/index.html. L’analyse de sécurité conseille de travailler en lecture seule pendant environ une journée tout en le surveillant : quels fichiers sont touchés, quels outils sont appelés, et si des erreurs se répètent. Si un outil se déclenche alors que vous ne l’attendiez pas, vous le découvrez pendant qu’il est encore inoffensif.
Lorsque les journaux paraissent propres, autorisez les écritures et gardez le shell exclu. Les noms ci-dessous proviennent de la même analyse tierce, vérifiez-les donc dans la liste d’outils de votre version de Serena :
read_only: false
included_optional_tools:
- edit_file
excluded_tools:
- execute_shell_command
Validez un arbre git propre avant chaque session. Ensuite, git diff montre exactement ce que Serena a modifié, et une seule commande git restore annule une mauvaise modification. Cette habitude vaut plus que tous les réglages ci-dessus.
Une courte liste de contrôle pour la première semaine :
/mcp indique Serena comme connecté et ne montre aucun outil shell./context et notez le nombre d’outils MCP.read_only: true jusqu’à ce que le tableau de bord vous paraisse ennuyeux.git diff après chaque session ayant écrit des fichiers..serena et lisez le contenu des mémoires.Un second avis sur votre configuration ne coûte pas cher. Claude Sonnet 5 sur PicassoIA lit le code, la configuration et les captures d’écran, il peut donc relire votre project.yml avant que vous l’appliquiez.
low, rapide et peu coûteuse. Utilisez high pour une configuration comportant beaucoup d’outils, et xhigh ou max seulement pour une configuration particulièrement emmêlée.max_image_resolution fait 0,5 mégapixel, ce qui suffit pour un graphique lisible.💡 Considérez la réponse comme le commentaire d’un relecteur, pas comme un verdict. Pour un autre angle, lancez le même prompt avec Claude Fable 5 ou GPT 5.6 Sol et comparez les points de désaccord.
| Erreur | Conséquence | Correction |
|---|---|---|
Oublier --context claude-code | Outils de fichiers en double, un outil shell et une charge de tokens plus lourde | Toujours passer l’indicateur |
--project-from-cwd global partout | Outils d’édition actifs dans tout dossier ouvert | Enregistrer par projet |
Intégrer auto-approve à l’aveugle | Moins d’occasions de refuser un appel risqué | Lire le crochet, puis décider |
| Exécuter depuis une URL git sans épingler | Vous exécutez ce que contient la branche ce jour-là | Installer le paquet ou épingler une étiquette |
Ne jamais vérifier /context | Le coût en tokens reste une supposition | Mesurer avant et après |
Valider .serena sans jeter un œil | Les fichiers de mémoire et les notes sont poussés dans un dépôt partagé | Ouvrir le dossier d’abord |
| Faire confiance à une longue session | L’agent s’écarte des outils de Serena | Utiliser les crochets et redémarrer |
Si vous écrivez sur vos outils, vous connaissez l’autre moitié du travail : les README, les articles de blog et les diapositives de conférence ont tous besoin de visuels qui semblent faire partie du même ensemble. Picasso IA réunit les modèles d’image au même endroit, pour tester un prompt, le modifier et comparer les résultats en quelques minutes. Pour les scènes photoréalistes, commencez avec Seedream 4.5 ou FLUX 1.1 Pro, puis parcourez le reste sur picassoia.com/en/all-models.
Décrivez une scène réelle avec un objectif, une direction de lumière et une texture, lancez-la, et ajustez un détail à la fois. Considérez le premier résultat comme un brouillon, car le troisième est généralement plus proche de ce que vous aviez imaginé. Ouvrez un modèle, tapez un prompt et voyez ce qui en ressort.
Choisissez votre langue
