jb-compta/docs/integration-indy-mcp.md

Intégration Indy via MCP (Claude Desktop)

Le serveur MCP mcp-server-indy-compta expose tes données Indy (transactions, clients, factures) en données structurées. C'est bien plus fiable que l'OCR. Deux usages : analyse en langage naturel et pont vers l'import de JB Compta.

⚠️ API non officielle d'Indy : ça peut casser si Indy change son interface, et c'est une zone grise vis-à-vis des CGU. L'authentification se fait par login navigateur (Chrome) ou un token JWT capturé qui expire et doit être renouvelé.

1. Installer et brancher le MCP sur Claude Desktop

Prérequis : Python 3.12+, uv, un compte Indy.

git clone https://github.com/stephaneberle9/fastmcp-creds.git
git clone https://github.com/stephaneberle9/python-indy-compta.git
git clone https://github.com/stephaneberle9/mcp-server-indy-compta.git
cd mcp-server-indy-compta && uv sync

Dans Claude Desktop → Settings… > Developer > Edit Config, ajoute :

{
  "mcpServers": {
    "indy-compta": {
      "command": "uv",
      "args": ["run", "--with-editable", "/chemin/vers/mcp-server-indy-compta",
               "mcp-server-indy-compta"]
    }
  }
}

Redémarre Claude Desktop. Au premier appel d'outil, un navigateur s'ouvre pour le login Indy.

2. Analyse en langage naturel

Exemples de questions à poser à Claude (avec le MCP connecté) :

• « Montre mes dépenses de juin 2026 groupées par catégorie. »
• « Quel est mon cash-flow du 1er trimestre ? »
• « Quelles transactions de dépense n'ont pas de justificatif attaché ? »
• « Liste mes factures en retard. »

3. Pont MCP → import JB Compta (le plus utile)

Demande à Claude de convertir tes transactions Indy au format CSV de l'app, puis colle le résultat dans la page Importer (/import/).

Prompt type à utiliser dans Claude Desktop :

En utilisant le MCP indy-compta, récupère toutes mes transactions de juin 2026. Donne-moi le résultat en CSV avec exactement ces colonnes, séparées par ; : date;libelle;categorie;activite;taux_tva;regime;montant Règles :

• date au format AAAA-MM-JJ ;
• montant signé (négatif = dépense, positif = encaissement) ;
• taux_tva = le taux affiché (0, 5.5, 10 ou 20) ;
• regime = intracom si la TVA est marquée « UE », sinon vide ;
• categorie = le nom exact de la catégorie Indy ;
• une seule ligne par transaction, pas de texte autour du CSV.

Tu colles ce CSV dans /import/ → Analyser → tu vérifies l'aperçu → Importer.

Avantage : Claude + le MCP font le fetch fiable et le mapping, l'app fait la création (déjà testée). Aucun token Indy à héberger sur ton serveur.

4. Plus tard : sync automatique côté serveur (optionnel)

Pour une automatisation totale (sans Claude Desktop), on pourrait intégrer la librairie python-indy-compta directement dans l'app (tâche planifiée qui tire les transactions et crée les opérations). À évaluer car cela demande :

• un token JWT statique sur le serveur (le login navigateur est impossible en headless), à renouveler à son expiration ;
• de mapper les objets de la librairie vers nos modèles (à valider avec ton compte) ;
• d'accepter la dépendance à une API non officielle.

Le pont CSV (section 3) couvre déjà 90 % du besoin sans cette complexité.