ffbb-data-client MCP server
Commit Nov 6, 2026Provides an asynchronous Python SDK to access French Basketball Federation data, including clubs, competitions, live scores, and standings.
Also known as nickdesi/ffbb-data-client
- Stars
- 8
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 6, 2026
- License
- Apache-2.0
What is ffbb-data-client MCP?
ffbb-data-client provides an asynchronous Python SDK to access French Basketball Federation data, including clubs, competitions, live scores, and standings.
Summary generated from the project's README
About ffbb-data-client MCP server
Accessing French basketball data through an asynchronous Python SDK is what developers can do with ffbb-data-client. This tool provides a way to interact with the official French Basketball Federation API to retrieve information about clubs, national and regional competitions, live scores, standings, and gym locations. It is designed for developers building mobile applications, interactive maps, or basketball directories.
The client is used locally via Python and handles all necessary authentication automatically through dynamic token bootstrapping, meaning no manual API keys are required. It features native asynchronous support for high-performance streaming of large datasets and includes a built-in FastAPI server for those who need to expose the data through a REST API.
What sets this client apart is its ability to perform geographic searches using GPS coordinates to find clubs within a specific kilometer radius. It also includes specialized tools like the NiveauExtractor for identifying competition levels and provides complete physical address resolution for sports halls, ensuring users get exact street names and postal codes rather than just raw names.
What you can do with it
- 1Monitor live match scoresRetrieve real-time updates and live scores for ongoing basketball matches.
- 2Retrieve official club contact detailsExtract administrative contact information such as emails and roles for club presidents or correspondents.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenickdesi/ffbb-data-client is public and reachablegithub.com/nickdesi/ffbb-data-client ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-06github.com/nickdesi/ffbb-data-client ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub🏀 API FFBB (Python SDK) — ffbb-data-client
Client Officiel & Asynchrone pour l'API de la Fédération Française de BasketBall (2026)
Le SDK Python moderne, ultra-rapide, asynchrone et typé pour exploiter l'API de la Fédération Française de BasketBall (FFBB) : clubs, compétitions nationales & régionales, scores en direct (lives), classements, calendriers, gymnases/salles et détection de niveau.
Alternative officielle, haute performance et maintenue aux anciens packages obsolètes ffbb-api-client et ffbb-api-client-v2.
⚡ Démarrage Rapide • 📍 Recherche Géo & Clubs • 🔥 Cas d'Usage • 🧵 Streaming Async • 🤖 Intégration IA / MCP • 🌐 API REST • 📖 Documentation
🔄 Cartographie API synchronisée :
162collections Directus OpenAPI cartographiées,17index Meilisearch surveillés.
[!NOTE] API Mobile Officielle (
v2.4.42+) : Utilisation native de l'origine mobile officiellehttps://api.ffbb.com/avec bootstrapping dynamique des jetons (/items/configuration) et émulation User-Agent Android officielle. L'intégralité des données Directus (y compris les feuilles de poules et les classements complets) est accessible en temps réel avec fallback résilient Meilisearch.
🏆 Pourquoi choisir ffbb-data-client ?
| Fonctionnalité | Ancien client (ffbb-api-client) |
ffbb-data-client (v2.4+) |
|---|---|---|
| Origine Directus & Anti-403 | ❌ Bloqué en 403 Forbidden (BunnyCDN) | ✅ API mobile api.ffbb.com + bootstrapping dynamique |
| Architecture Asynchrone Native | ❌ 100% bloquant / synchrone | ✅ Async native (async/await + aiter) |
| Modèles de Données & Typage | ❌ Dictionnaires bruts sans type | ✅ Dataclasses & Pydantic v2 validés |
| Recherche Meilisearch Instantanée | ❌ Partielle ou absente | ✅ Multi-index (Clubs, Salles, Poules, 3x3) |
| Recherche Géographique par GPS | ❌ Non disponible | ✅ Rayon kilométrique autour de coordonnées |
| Streaming de Masse (Pagination auto) | ❌ Manuelle, risque d'OOM | ✅ Générateurs streaming aiter_all_* |
| Résolution d'Adresses de Salles | ❌ Nom brut souvent vide | ✅ Résolution physique complète (Gymnase, Rue, CP, Ville) |
| Compatibilité IA & Agents MCP | ❌ Incompatible | ✅ Connecteur natif Model Context Protocol |
| Couverture de Tests & Fiabilité | ⚠️ < 30% | ✅ 680+ tests unitaires & 100% Zero-Red CI |
📦 Installation
Installez la dernière version stable via pip ou uv :
# Via pip standard
pip install ffbb-data-client
# Via uv (recommandé pour la rapidité)
uv add ffbb-data-client
Options supplémentaires
# Avec le serveur d'API REST FastAPI intégré
pip install "ffbb-data-client[server]"
# Pour le développement local et la suite de tests complète
pip install "ffbb-data-client[testing]"
Prérequis : Python >=3.10.
⚡ Démarrage Rapide (30 secondes)
Aucun compte développeur ni clé d'API compliquée : FFBBDataClient.create() résout et rafraîchit automatiquement les tokens publics nécessaires :
from ffbb_data_client import FFBBDataClient
# Initialisation en une seule ligne (zéro configuration requise)
client = FFBBDataClient.create()
# 1. Rechercher un club de basket en France
clubs = client.search_organismes("Clermont", limit=3)
for club in clubs.hits:
print(f"🏀 {club.nom} ({club.codePostal} {club.commune}) - ID: {club.id}")
# 2. Consulter les scores et matchs en direct (Lives FFBB)
lives = client.get_lives()
print(f"Matchs suivis en direct : {len(lives)}")
# 3. Explorer les rencontres d'une compétition (ex: Nationale 1 Masculine)
rencontres = client.search_rencontres("NM1", limit=5)
for m in rencontres.hits:
print(f"📅 {m.date_rencontre} : {m.equipe1} vs {m.equipe2}")
📍 Recherche Géographique & Clubs de France
Idéal pour concevoir des applications mobiles, des cartes interactives ou des annuaires de basketball :
🌍 Trouver tous les clubs autour d'un point GPS
# Exemple : Clubs dans un rayon de 20 km autour de Lyon / Clermont-Ferrand
clubs = client.search_organismes_by_geo(
lat=45.7772,
lng=3.0870,
radius_km=20,
limit=15,
)
for club in clubs.hits:
print(f"📍 {club.nom} à {club.commune} [{club.geo}]")
🔍 Recherche ciblée par Code Postal, Ville ou Catégorie
# Filtrer par département ou code postal
organismes = client.search_organismes(
"Basket",
filter=['codePostal = "63000"'],
sort=["nom:asc"],
limit=10,
)
🔥 Recettes & Cas d'Usage Concrets
from ffbb_data_client import FFBBDataClient
client = FFBBDataClient.create()
# Récupération complète d'une poule de championnat
poule = client.get_poule(11111)
print(f"Championnat : {poule.nom}")
for rk in poule.classement or []:
print(f"#{rk.position} {rk.organisme_nom} - {rk.points} pts ({rk.victoires}V - {rk.defaites}D)")
# Fini les adresses partielles : résolution déterministe certifiée FFBB
salles = client.search_salles("Maison des Sports", limit=3)
for salle in salles.hits:
print(f"🏟️ {salle.nom} : {salle.adresse}, {salle.codePostal} {salle.ville}")
from ffbb_data_client import NiveauExtractor, NiveauType
# Détection intelligente du niveau hiérarchique
niveau = NiveauExtractor.extract_niveau("RÉGIONALE MASCULINE SENIORS - DIVISION 2")
print(niveau.type) # NiveauType.REGIONAL
print(niveau.division) # 2
# Contacts administratifs officiels
contacts = client.get_club_contacts(organisme_id=9326)
if contacts:
print(f"Club : {contacts.club_contact.nom}")
print(f"Email : {contacts.club_contact.email}")
for membre in contacts.membres:
print(f" - {membre.role} : {membre.prenom} {membre.nom} ({membre.email})")
🧵 Haute Performance & Streaming Asynchrone
Pour traiter de gros volumes de données sans saturer la mémoire vive ni bloquer la boucle d'événements :
import asyncio
from ffbb_data_client import FFBBDataClient
async def main():
client = FFBBDataClient.create()
# Streaming asynchrone mémoire-constant (aiter)
count = 0
async for rencontre in client.aiter_all_rencontres(page_size=100, max_items=500):
count += 1
if count % 100 == 0:
print(f"Traitement du match #{count} : {rencontre.id}")
# Recherche asynchrone non-bloquante
results = await client.search_organismes_async("ASVEL")
print(f"Résultats trouvés : {results.estimated_total_hits}")
asyncio.run(main())
🤖 IA, Agents & MCP Server
Le SDK ffbb-data-client est le moteur officiel du serveur Model Context Protocol (MCP) pour le basket français.
Il permet aux LLMs (Claude, ChatGPT, Cursor, Gemini, Antigravity) d'interagir nativement avec les championnats de basket :
- 💬 "Quels sont les prochains matchs du SCBA ce week-end ?"
- 💬 "Donne-moi le classement de la Poule Haute U13M2."
- 💬 "Quelle est l'adresse exacte de la salle pour le match de samedi ?"
👉 Découvrez le projet dédié : FFBB-MCP-Server
🌐 Serveur REST FastAPI Embarqué
Besoin d'une API web pour votre application React, Vue, Next.js ou mobile ? ffbb-data-client intègre une API FastAPI prête à l'emploi :
# Démarrer le serveur API local
uvicorn ffbb_data_client.api:app --host 0.0.0.0 --port 8000 --reload
Accédez ensuite à la documentation Swagger interactive sur http://localhost:8000/docs !
Endpoints phares :
GET /health: Statut de santé et horodatage UTC.GET /api/v1/club/{id}/matches: Calendrier optimisé du club avec adresses de salles résolues.GET /api/v1/lives: Matchs en direct agrégés.
📚 Référence des Méthodes (Sync & Async)
💡 Pattern standard : Toutes les méthodes existent en version synchrone (
nom()) et asynchrone (nom_async()).
| Domaine | Méthodes (Sync & Async) | Description |
|---|---|---|
| 🌐 Multi-Search | multi_search()multi_search_async() |
Recherche globale simultanée sur tous les index Meilisearch |
| 🏀 Clubs & Organismes | search_organismes()search_organismes_async() |
Recherche par nom, commune, département ou code postal |
| 📍 Géo-Localisation | search_organismes_by_geo()search_organismes_by_geo_async() |
Recherche de clubs par rayon GPS (lat/lng, km) |
| 👤 Contacts Club | get_club_contacts()get_club_contacts_async() |
Fiche contacts officielle (président, correspondants, emails) |
| 📅 Rencontres & Matchs | search_rencontres()search_rencontres_async() |
Calendriers, résultats de matchs et scores |
| ⚡ Streaming Continu | aiter_all_rencontres() |
Générateur asynchrone paginé en streaming (aiter) |
| 🏟️ Salles & Gymnases | search_salles()search_salles_async() |
Adresses physiques complètes, gymnases et coordonnées |
| 🏆 Compétitions | search_competitions()search_competitions_async() |
Championnats nationaux (NM1, LF2...), régionaux, départ. |
| 📊 Poules & Classement | get_poule()get_poule_async() |
Classement officiel complet (V/D, pts) et matchs de poule |
| ⚡ Scores en Direct | get_lives()get_lives_async() |
Flux officiel des scores en temps réel (Lives FFBB) |
| 🎯 Tournois 3x3 | search_tournois()search_tournois_async() |
Tournois officiels homologués 3x3 FFBB |
🛠️ Robustesse, CI/CD & Découverte Quotidienne
- Origine Directus & API Mobile : Origine officielle
https://api.ffbb.com/issue du reverse engineering de l'app mobile (pullzone 5204911). Les jetons Directus et Meilisearch sont découverts à chaud via/items/configuration. En cas d'indisponibilité temporaire de l'upstream, un disjoncteur bascule sur Meilisearch avec signalement défensif (degraded). - Auto-Résolution des Tokens : Découverte et rotation dynamiques des jetons Bearer Directus et Meilisearch sans configuration requise.
- Découverte Quotidienne du Schéma : Un cron GitHub Actions analyse chaque matin à 5h17 UTC l'OpenAPI spec officielle de la FFBB et détecte automatiquement tout nouveau champ ou collection Directus.
- Cache Intelligent Sécurisé : Gestionnaire de cache HTTP
hishelavec SQLite distinct pour les flux synchrones et asynchrones. - CodeQL & Zéro Dette : Conformité aux normes de sécurité, zéro alerte d'injection de log, 100% typé.
⚙️ Configuration & Variables d'Environnement
Le SDK fonctionne instantanément sans configuration. Des variables d'environnement permettent de surcharger les comportements réseaux si nécessaire :
| Variable | Description | Valeur par défaut |
|---|---|---|
API_FFBB_BASE_URL |
URL de base du backend Directus | https://api.ffbb.com/ |
FFBB_USER_AGENT |
En-tête User-Agent transmis aux requêtes | FFBB Android Mobile (1.6.7.42) |
API_FFBB_APP_BEARER_TOKEN |
Jeton Directus explicite (override l'auto-résolution) | Auto-résolu dynamiquement |
MEILISEARCH_BEARER_TOKEN |
Jeton Meilisearch explicite (override l'auto-résolution) | Auto-résolu dynamiquement |
HTTP_PROXY / HTTPS_PROXY |
Proxy HTTP/HTTPS sortant (ex: swarm / environnement conteneurisé) | Aucun |
🤝 Contribuer
Les contributions, signalements de bugs et suggestions sont les bienvenus !
- Forkez le projet.
- Créez une branche (
git checkout -b feat/ma-nouvelle-fonctionnalite). - Installez l'environnement de développement :
pip install -e ".[testing]". - Vérifiez que tous les tests passent :
pytest tests/etpre-commit run --all-files. - Ouvrez une Pull Request claire et documentée.
📄 Licence
Distribué sous la licence Apache-2.0. Voir LICENSE.txt pour plus de détails.
Développé avec passion pour la communauté du basketball français. 🇫🇷🏀
Si cette bibliothèque vous est utile, n'hésitez pas à ajouter une étoile ⭐ sur GitHub pour encourager le projet !
ffbb-data-client MCP questions
Does it require an API key?
No, the client automatically resolves and refreshes the necessary public tokens.
Can I run a local web server with this?
Yes, it includes an embedded FastAPI REST server that can be started via uvicorn.