Serveur MCP

Badlen livre un serveur MCP qui expose huit outils par-dessus la surface /api/v1. C’est par là qu’un relevé entier entre dans le produit d’un seul coup.

Vos relevés ──▶ Claude Code / Desktop ──▶ outils MCP ──▶ Badlen /api/v1
                 lit et extrait           import_transactions    dédoublonne, écrit
                 (votre abonnement)

Votre client Claude lit les fichiers, sur votre machine, sur votre abonnement. Le serveur est un pont stdio et ne porte aucun modèle : Badlen n’appelle donc jamais l’API d’Anthropic, aucune clé de modèle n’est jamais stockée sur le serveur, et rien d’un relevé n’atteint Badlen hormis des opérations déjà extraites.

Note

Sans client Claude, cette page ne vous apporte rien : les opérations se saisissent alors une à une depuis le journal d’un compte.

L’installer

1. Ayez une instance Badlen en marche, et sachez à quelle adresse vous la joignez. Une instance installée depuis Docker Compose répond sur http://localhost:8080 : ce numéro est le WEB_PORT de votre .env, et le changer là change cette adresse. Derrière un proxy inverse, indiquez l’adresse que sert le proxy. Les exemples ci-dessous portent la valeur par défaut, qui est aussi celle que le serveur prend quand BADLEN_URL n’est pas renseignée.

2. Ayez Node et pnpm sur la machine où tourne le client. Le serveur est un script Node que votre client Claude démarre directement, hors de Docker, si bien qu’une machine qui n’a suivi que Installation est à court des deux : node 22.12 ou plus récent et pnpm 12, les versions que le dépôt épingle dans son package.json racine.

3. Lancez pnpm install à la racine du dépôt, ce qui tire le SDK MCP.

4. Émettez une clé API portant exactement cinq droits : accounts:read, dashboard:read, positions:read, accounts:write et transactions:write.

5. Déclarez le serveur auprès de votre client. Le chemin vers server.mjs doit être absolu : le client ne le démarre pas depuis l’intérieur du dépôt.

   Claude Code

   claude mcp add badlen \
     -e BADLEN_URL=http://localhost:8080 \
     -e BADLEN_API_KEY=sk_your_key \
     -- node /absolute/path/to/packages/mcp/src/server.mjs

   Claude Desktop

   claude_desktop_config.json

   {
     "mcpServers": {
       "badlen": {
         "command": "node",
         "args": ["/absolute/path/to/packages/mcp/src/server.mjs"],
         "env": {
           "BADLEN_URL": "http://localhost:8080",
           "BADLEN_API_KEY": "sk_your_key"
         }
       }
     }
   }

Une clé à une case près ne se plaint pas tout de suite

Une clé à qui il manque un droit est acceptée à la création. L’échec arrive plus tard, sous la forme d’un 403, la première fois que Claude appelle le seul outil qui en avait besoin, pendant que tous les autres continuent de fonctionner. Cochez les cinq.

Les huit outils

Outil	Ce qu’il fait
list_accounts	Les comptes, avec id, nom, type et valeur, pour que Claude sache où importer
get_net_worth	Le patrimoine net et l’allocation par classe d’actifs
get_positions	Les lignes par titre, avec les plus-values latentes et réalisées
create_account	Créer un compte où importer
set_balance	Poser le solde d’un compte manuel sur un jour donné
add_holding	Ajouter une ligne de fonds ou d’ETF par son ISIN, cours résolu automatiquement
reconcile_transactions	Simulation : comparer un envoi au compte sans rien écrire
import_transactions	Écrire l’envoi, dédoublonné

Aucun d’eux ne supprime quoi que ce soit.

Importer un relevé

Pointez votre client sur les fichiers et demandez-lui, en toutes lettres, de les importer dans Badlen. Il normalise les opérations, appelle reconcile_transactions pour voir les doublons et vous poser ses questions, puis appelle import_transactions une fois que vous avez répondu. Rejouer le même relevé est sans danger : les doublons sont écartés. Ce que ce second appel fait de l’envoi est sur la page de l’import.

Quand un appel échoue

Ce que vous voyez	Ce que cela veut dire
401 sur tous les outils	La clé est absente, inconnue, révoquée ou expirée
403 sur un seul outil	La clé a été émise sans le droit dont cet outil a besoin
400 sur un montant	Les montants voyagent en chaînes décimales ; un nombre JSON est refusé net
400 sur une date	Une date fait dix caractères, YYYY-MM-DD, et non un horodatage

Toutes les routes qu’atteignent ces outils sont écrites dans la référence de l’API REST, générée depuis le contrôleur plutôt que tapée à la main.