Doctolib MCP

Serveur MCP non officiel qui donne à Claude (ou à tout client MCP) un accès complet à l'API publique de Doctolib : chercher des praticiens autour d'un lieu, lister tous les créneaux libres d'une spécialité dans un rayon, lire les infos pratiques d'un cabinet, et être alerté dès qu'un créneau se libère.

« Trouve-moi tous les rendez-vous de dermatologue dans les 15 km autour de Clermont-Ferrand d'ici un mois. » « Surveille le Dr X et préviens-moi sur mon téléphone dès qu'un créneau s'ouvre avant le 15 octobre. »

Aucun compte Doctolib n'est nécessaire : le serveur utilise uniquement les données publiques que le site affiche à tout visiteur. La réservation, elle, se fait toujours sur Doctolib (lien direct fourni, lieu et motif pré-sélectionnés).

Fonctionnalités

• Recherche géographique : spécialité + ville / code postal / adresse + rayon, triée par distance, avec secteur de conventionnement, paiement, langues, motif, acceptation des nouveaux patients.

• Tous les créneaux d'une zone en un appel (find_slots) : chaque agenda est interrogé, les créneaux sont remis dans l'ordre chronologique, avec la raison quand il n'y en a pas (« agenda fermé », « prochain créneau le … »).

• Détail d'un praticien : tous ses motifs (réservés aux patients suivis ? restrictions d'âge ? vidéo ?), agendas fermés, téléphone du cabinet, horaires d'ouverture, carte Vitale, moyens de paiement.

• Créneaux sur la période voulue (au-delà des 15 jours par appel de Doctolib), avec remplaçants et créneaux sur demande.

• Surveillance d'un praticien ou de toute une zone, avec notifications macOS, push téléphone (ntfy, gratuit) ou webhook (n8n, Make, Zapier…).

• Référentiels : 123 spécialités, autocomplétion Doctolib (spécialités, actes, praticiens), sitemaps publics.

21 outils au total : voir docs/TOOLS.md. Les endpoints Doctolib sous-jacents sont documentés dans docs/API.md.

Related MCP server: doctolib-mcp

Installation

Prérequis : Python ≥ 3.11 et uv.

git clone https://github.com/arvernesmotion/Doctolib-MCP.git
cd Doctolib-MCP
uv sync

Claude Code

claude mcp add doctolib --scope user -- uv --directory /chemin/vers/Doctolib-MCP run doctolib-mcp

Claude Desktop

Dans claude_desktop_config.json (voir examples/claude_desktop_config.json) :

{
  "mcpServers": {
    "doctolib": {
      "command": "uv",
      "args": ["--directory", "/chemin/vers/Doctolib-MCP", "run", "doctolib-mcp"]
    }
  }
}

Autres clients MCP

Le serveur parle MCP en stdio : commande uv --directory <dossier> run doctolib-mcp.

Exemples de demandes

Alertes de créneaux

1. Choisir les canaux (une fois) : demandez à Claude « configure les notifications avec un topic ntfy » (configure_notifications), puis installez l'app ntfy (iOS / Android) et abonnez-vous au topic renvoyé. Gardez-le secret : quiconque le connaît reçoit vos alertes. Un webhook_url permet aussi de relayer vers n8n, Slack…

2. Créer une surveillance : watch_practitioner (un praticien) ou watch_area (toute une zone).

3. Planifier la vérification : la commande doctolib-mcp-watch fait une passe et notifie les nouveaux créneaux. Lancez-la toutes les 5 à 10 minutes :

   • macOS (launchd) : adapter examples/launchd.plist puis

     cp examples/launchd.plist ~/Library/LaunchAgents/fr.doctolib-mcp.watch.plist
     launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/fr.doctolib-mcp.watch.plist

     ⚠ Protection macOS : launchd refuse d'exécuter un script situé dans ~/Documents, ~/Desktop ou ~/Downloads (« Operation not permitted »). L'exemple appelle donc .venv/bin/python -m doctolib_mcp.watch. Si la passe reste bloquée malgré tout, clonez le dépôt hors de ces dossiers (ex. ~/Services/Doctolib-MCP).

   • Linux (systemd) : examples/doctolib-mcp-watch.service et examples/doctolib-mcp-watch.timer.

   • cron : */10 * * * * cd /chemin/vers/Doctolib-MCP && uv run doctolib-mcp-watch >> ~/.doctolib-mcp/watch.log 2>&1

Au premier passage, les créneaux déjà ouverts sont signalés ; ensuite, uniquement les nouveaux. Un créneau qui disparaît puis réapparaît (annulation d'un autre patient) est signalé à nouveau : ce sont les meilleures occasions.

Configuration

Limites à connaître

• Connexion résidentielle requise pour les créneaux. Doctolib (Cloudflare) bloque availabilities.json depuis les IP de datacenter (Vercel, AWS, la plupart des VPS…) : réponse 403. Faites tourner le serveur sur votre ordinateur. La recherche et les infos pratiques passent, elles, depuis n'importe où.

• Pas de réservation automatique. Réserver exige votre compte Doctolib ; le serveur fournit le lien direct (lieu + motif pré-sélectionnés). Le créneau lui-même ne peut pas être pré-sélectionné.

• Seuls les agendas ouverts en ligne sont visibles. Beaucoup de spécialistes n'ouvrent leur agenda que par vagues, ou réservent certains motifs à leurs patients suivis ; c'est précisément là que la surveillance est utile.

• Le motif principal renvoyé par la recherche est choisi par Doctolib et peut être un motif réservé (« Ancien patient du Dr X ») : practitioner_booking_info liste tous les motifs.

• Tarifs chiffrés, accessibilité, RPPS ne sont exposés que dans un endpoint réservé aux navigateurs : non couverts.

• API non officielle : Doctolib peut en changer le format à tout moment.

Usage responsable

Ce projet n'est ni affilié à Doctolib, ni approuvé par Doctolib. Il est destiné à un usage personnel, pour trouver un rendez-vous médical plus facilement. Le robots.txt et les conditions d'utilisation de Doctolib encadrent l'accès automatisé à leurs services : restez à faible débit (réglage par défaut ≈ 3 requêtes/s, surveillances toutes les 5–10 min), ne republiez pas et ne revendez pas les données, et n'utilisez pas cet outil pour accaparer des créneaux au détriment d'autres patients. Vous êtes responsable de l'usage que vous en faites.

Développement

src/doctolib_mcp/
├── client.py     # HTTP : en-têtes navigateur, limitation de débit globale, reprises sur 429
├── api.py        # un wrapper par endpoint Doctolib + normalisation
├── geo.py        # géocodage (geo.api.gouv.fr, api-adresse.data.gouv.fr)
├── finder.py     # moteur « tous les créneaux d'une zone »
├── store.py      # surveillances, configuration, notifications
├── watch.py      # passe de surveillance (commande doctolib-mcp-watch)
├── server.py     # serveur MCP (21 outils + 1 ressource)
└── data/specialities.json

Test de bout en bout contre le vrai site (depuis une connexion résidentielle) :

uv run python tests/smoke_live.py

Il démarre le serveur en stdio, appelle chaque outil et affiche OK / ERR (les surveillances de test sont écrites dans un dossier temporaire).

Licence

MIT