En bref

  • Problème : un ami voulait piloter son CRM Pipedrive avec Claude, sans donner à l’agent un accès large et flou à toutes ses données commerciales.
  • Ce que j’ai testé : les options MCP Pipedrive existantes, puis un petit serveur local TypeScript, en mock, en stdio, et enfin contre un vrai compte Pipedrive avec des objets jetables préfixés MCP LAB -.
  • Résultat : le cœur du workflow commercial fonctionne en live pour créer, relire, modifier et nettoyer organisations, personnes, leads, deals, notes, activités, relances et clôtures. Le test produit a été sauté parce que le compte n’avait aucun produit disponible.
  • À retenir : un MCP CRM utile n’est pas celui qui expose toute l’API. C’est celui qui donne assez d’actions pour travailler, avec des limites visibles avant le premier vrai write.
  • Repo lié : pezzos/pipedrive-mcp-lab.

Le besoin de départ

Le point de départ était simple : un ami voulait demander à Claude des choses qu’il fait déjà dans Pipedrive. Retrouver un deal, préparer une relance, créer une activité, qualifier un lead, déplacer une opportunité, ajouter une note après un appel.

Sur le papier, MCP est une bonne forme pour ça. Au lieu de coller une documentation API dans un prompt, on expose des outils avec des noms, des paramètres, des validations et des erreurs plus lisibles. Mais un CRM n’est pas un jeu de données neutre. Il contient des noms, des emails, des téléphones, des montants, des notes commerciales, parfois des informations que personne ne veut retrouver dans un log de test.

La question n’était donc pas seulement : « est-ce que Claude peut appeler Pipedrive ? » C’était plutôt : « quelle surface peut-on donner à Claude pour aider un commercial, sans transformer l’agent en utilisateur tout-puissant ? »

Les raccourcis qui existaient déjà

Je n’ai pas commencé par coder. J’ai d’abord regardé les chemins déjà disponibles.

Le repo WillDent/pipedrive-mcp-server était le plus proche de ce que je pouvais adapter vite : TypeScript, MCP SDK, Pipedrive, stdio et SSE. C’était une bonne base à lire, mais je voulais un lab encore plus contrôlé : pas de transport réseau au départ, pas de SSE, pas de CORS, pas de question d’hébergement.

pipedrive-mcp sur PyPI part dans une direction plus large, avec beaucoup d’outils et une logique CRUD plus complète. C’est utile si l’objectif est de couvrir vite une grande partie de l’API. Pour ce lab, c’était justement le risque : plus l’agent voit d’actions, plus il faut être précis sur les permissions, les confirmations, les erreurs, et les données sensibles.

Il y a aussi des options gérées comme Apideck, Pipedream ou Activepieces. Elles peuvent être plus adaptées si on veut déléguer OAuth, le stockage des secrets, ou la maintenance d’un catalogue de connecteurs. Ici, je cherchais plutôt l’inverse : comprendre la surface minimale et garder le code inspectable.

Ce que j’ai construit

J’ai gardé un serveur MCP local en TypeScript, avec le SDK MCP officiel, transport stdio seulement. Pas de serveur HTTP. Pas d’OAuth. Pas de déploiement distant. Le token Pipedrive reste local, dans .env, et le client envoie le secret avec le header x-api-token, pas dans l’URL.

La première version était volontairement petite. Puis les tests ont montré que, pour un commercial, la lecture seule n’était pas suffisante. Un MCP qui retrouve un deal mais ne peut jamais préparer une relance ou marquer une activité comme faite reste une démo.

La surface actuelle expose 61 outils, mais ils sont regroupés autour de quelques usages simples :

  • lire et chercher deals, personnes, organisations, leads, pipelines, stages, activités, notes, utilisateurs, champs custom et types d’activité ;
  • créer et modifier les objets commerciaux courants ;
  • déplacer un deal, le marquer gagné ou perdu, convertir un lead ;
  • créer une note, replanifier ou terminer une activité ;
  • journaliser un appel et créer une relance ;
  • ajouter participants, followers et produits à un deal quand le compte le permet ;
  • supprimer uniquement des objets lab-préfixés pour nettoyer les tests.

La partie importante n’est pas le nombre d’outils. C’est le fait que les écritures sont fermées par défaut. Il faut PIPEDRIVE_ENABLE_WRITES=true, dry_run=false, et une confirmation. Pour les tests live, j’ai ajouté une confirmation spéciale : confirm_lab_write=true. Elle permet à une session de test d’écrire uniquement sur des objets dont le nom commence par MCP LAB -, sans connaître le secret PIPEDRIVE_WRITE_CONFIRMATION.

Le test qui a changé mon avis

Le premier lab prouvait seulement la structure : build TypeScript, tests mockés, serveur MCP lancé en stdio, token absent des URLs, et quelques lectures live avec les écritures désactivées. C’était utile, mais pas suffisant pour l’angle de départ. « Piloter son CRM » implique au moins une boucle création, relecture, modification et nettoyage.

Le 24 mai 2026, on a donc rejoué le test avec de vraies écritures, mais seulement sur des objets synthétiques préfixés MCP LAB -. La trace factuelle est gardée dans RESULTATS.md, séparée de cette note plus narrative.

Le dernier run, MCP LAB - 2026-05-24 - AP-RETEST-1423, a validé les corrections qui comptaient :

  • une organisation peut être créée, relue, renommée puis supprimée ;
  • une personne peut être créée et modifiée avec email et téléphone ;
  • une activité liée à une personne passe par participants, au lieu d’envoyer un person_id que l’API refuse en écriture ;
  • un lead sans personne ni organisation est refusé côté MCP ;
  • un lead lié à une personne ou une organisation peut être créé, modifié, relu puis supprimé ;
  • les suppressions laissent les états attendus selon les objets : tombstone is_deleted=true, active_flag=false, ou 404 pour un lead supprimé.

Un test précédent avait déjà validé le cycle deal, note, activité, workflow appel + relance, closing gagné/perdu, participant et follower. Le seul scénario commercial prévu qui reste non exécuté en live est l’ajout d’un produit à un deal, simplement parce que pipedrive_list_products a retourné zéro produit dans le compte testé.

Les petites erreurs qui valaient le lab

Les tests mockés ne suffisent pas pour une API métier. Ils prouvent qu’on envoie la forme qu’on pense envoyer, pas forcément la forme que Pipedrive accepte aujourd’hui.

Le live a sorti quatre corrections très concrètes :

  • l’address d’une organisation n’était pas un simple champ texte fiable sur l’endpoint utilisé, donc je l’ai retiré du schéma MCP au lieu de le laisser mentir ;
  • email et phone côté personne devaient être transformés en tableaux emails et phones pour coller à la forme API v2 ;
  • person_id sur une activité devait être représenté via participants ;
  • la valeur d’un lead devait être envoyée avec amount et currency, et le MCP refuse maintenant une valeur sans devise.

Ce sont des détails assez ennuyeux, mais c’est précisément ce que je voulais obtenir du lab. L’article n’aurait pas dû raconter « j’ai branché Claude à Pipedrive » tant que ces écarts n’étaient pas visibles.

Ce que je ne prétends pas

Je ne considère pas ce MCP comme un remplacement complet de l’UI Pipedrive.

Il couvre le cœur du quotidien commercial que je voulais tester : chercher, créer, modifier, relancer, noter, avancer et clôturer des objets CRM. Il ne couvre pas encore ce que l’UI fait autour : envoi ou synchronisation email, upload et téléchargement de fichiers, rapports, dashboards, automations, webhooks, administration, OAuth, hébergement distant, ni validation fine des headers de pagination et de rate limit.

Je ne le brancherais pas tel quel sur un CRM client rempli de vraies données. Pour ça, il faudrait au minimum des profils de permissions, une vraie séparation des outils read/write, des confirmations mieux intégrées au client MCP, une stratégie de logs, et probablement un modèle OAuth ou proxy si on sort du poste local.

Ce que je garderais pour l’ami

Pour un usage local accompagné, je garderais trois règles.

D’abord, l’agent doit commencer par lire. Un commercial peut demander : « retrouve le deal de cette personne », « montre les activités ouvertes », « prépare une relance ». La lecture donne du contexte sans modifier le CRM.

Ensuite, les écritures doivent rester explicites. Je préfère un outil log_call_and_schedule_follow_up à une suite d’appels API abstraits que Claude doit enchaîner avec des IDs. Un bon outil MCP encode un geste métier, pas seulement un endpoint.

Enfin, le nettoyage et les limites doivent être visibles dans le repo. Le fichier RESULTATS.md n’est pas décoratif : il dit ce qui a été testé, ce qui a échoué, ce qui a été corrigé, et ce qui reste hors champ.

Le repo contient

  • un serveur MCP TypeScript en transport stdio ;
  • un client Pipedrive qui garde le token dans le header x-api-token ;
  • 61 outils autour de la lecture CRM et des workflows commerciaux gardés ;
  • des validations Zod, un mode dry-run, un préfixe lab obligatoire par défaut pour les écritures réelles, et confirm_lab_write=true pour les tests jetables ;
  • des tests unitaires et des tests MCP stdio avec API Pipedrive mockée ;
  • un TEST_PROMPT.md pour rejouer les validations depuis une session MCP ;
  • un RESULTATS.md qui sépare les preuves mockées, les lectures live, les écritures jetables et les limites restantes.

Il sert à

  • inspecter une façon prudente de connecter Claude ou Codex à Pipedrive ;
  • lancer un MCP local sans exposer de serveur réseau ;
  • tester les outils sur un compte Pipedrive de lab ;
  • reprendre les garde-fous dans un connecteur plus sérieux.

Il ne sert pas à

  • brancher un CRM client sans revue ;
  • remplacer toute l’UI Pipedrive ;
  • démontrer que les produits, emails, fichiers, rapports et automations sont couverts ;
  • résoudre OAuth, l’hébergement distant ou les permissions multi-utilisateurs ;
  • donner à Claude un accès CRUD généraliste sans confirmation.

Le repo est ici : github.com/pezzos/pipedrive-mcp-lab.