API FFBB : un SDK Python et un serveur MCP pour exploiter les données du basket français
Sur Hoops 63, on parle terrain, coaching et résultats. Mais derrière chaque article, il y a aussi des outils. Voici ceux que j’ai construits pour accéder aux données officielles de la FFBB en Python, et pour permettre aux assistants IA de parler basket.
1. ffbb-data-client : le SDK Python pour l’API FFBB
Quand on suit le basket jeunes dans le Puy-de-Dôme, on passe son temps sur le site de la FFBB à chercher des classements, des calendriers, des résultats. Chaque saison, chaque poule, chaque phase. À la main, c’est long. J’ai donc automatisé tout ça.
ffbb-data-client est un package Python open source qui se connecte à l’API FFBB et à ses index Meilisearch. Il gère les tokens automatiquement, met en cache les réponses, et retourne des données typées avec Pydantic. On peut l’utiliser en synchrone ou en async.
Concrètement, en quelques lignes de code, on peut :
- Rechercher un club, une compétition ou une salle par nom ou par géolocalisation
- Récupérer le classement complet d’une poule
- Lire les résultats d’une rencontre avec la feuille de match
- Suivre les scores en direct (lives)
- Accéder aux fiches des officiels et des entraîneurs
pip install ffbb-data-client
from ffbb_data_client import FFBBDataClient
client = FFBBDataClient.create()
# Chercher tous les clubs autour de Clermont-Ferrand
clubs = client.search_organismes_by_geo(
lat=45.7772, lng=3.0870, radius_km=20
)
# Classement d'une poule
classement = client.get_classement(poule_id=12345)
# Scores en direct
lives = client.get_lives()
Le code source est sur GitHub et la documentation complète sur la page officielle du projet.
2. FFBB MCP Server : l’IA parle basket français
Depuis quelques mois, les assistants IA comme Claude, GitHub Copilot ou ChatGPT peuvent se connecter à des sources de données externes via le protocole MCP (Model Context Protocol). J’ai construit un serveur MCP dédié aux données de la FFBB.
En pratique, ça veut dire qu’un assistant IA peut répondre à des questions comme :
- « Quel est le classement de la poule U13 R3 du Puy-de-Dôme ? »
- « Quand est le prochain match du Stade Clermontois U13 ? »
- « Quel a été le dernier résultat de Gerzat Basket U18 ? »
- « Quels clubs de basket existent dans un rayon de 15 km autour de Gerzat ? »
L’IA interroge directement l’API FFBB en temps réel. Pas de données périmées, pas de résultats inventés.
Ce que le serveur MCP FFBB peut faire :
- Chercher un club par nom ou géolocalisation
- Récupérer le bilan complet d’une équipe sur la saison
- Afficher le classement d’une poule
- Donner le dernier résultat ou le prochain match d’une équipe
- Lister les scores en direct
Le projet est disponible sur GitHub : FFBB-MCP-Server. Il s’installe en une commande et se connecte à Claude Desktop, VS Code, Cursor ou n’importe quel client MCP.
3. Pourquoi j’ai construit ces outils
Je suis bénévole dans deux clubs du Puy-de-Dôme (Stade Clermontois et Gerzat Basket) et je tiens ce blog depuis plusieurs saisons. Chaque semaine, je récupère des classements, des résultats, des calendriers sur le site de la FFBB pour alimenter les articles de Hoops 63.
Au bout d’un moment, j’ai voulu que ça aille plus vite. Plutôt que de naviguer manuellement entre les pages, j’ai écrit un client Python qui fait le travail en quelques secondes. Puis j’ai ajouté la couche MCP pour que mes assistants IA puissent aussi accéder à ces données quand je leur pose des questions sur le basket.
Ces outils sont gratuits, open source, et indépendants de la FFBB. Ils s’adressent aux développeurs, aux coachs qui veulent automatiser leur suivi de saison, et aux passionnés de données sportives.
Liens utiles :
- ffbb-data-client sur PyPI (pip install ffbb-data-client)
- Documentation et page officielle du SDK
- Code source du SDK sur GitHub
- Serveur MCP FFBB sur GitHub