🏀 FFBB MCP Server

Le basket français officiel, directement dans vos assistants IA.

Serveur MCP pour consulter calendriers, classements, bilans, résultats et scores live de la FFBB.

🌐 Site · 🧩 Extension VS Code · 📚 Documentation · 💬 Support

⭐ Si ce serveur MCP FFBB vous est utile pour vos assistants IA, n'hésitez pas à laisser une étoile sur GitHub ! ⭐

⚡ Démarrage express (< 2 min)

[!TIP] Aucune installation requise : le serveur est hébergé publiquement. Ajoutez simplement l'endpoint MCP à votre client :

https://ffbb.desimone.fr/mcp

Puis posez vos questions en langage naturel :

« Quel est le prochain match des U15 de mon club ? » « Donne-moi le classement de la poule et le dernier résultat. » « Y a-t-il des matchs en direct ce soir ? »

👉 Voir la section Installation pour brancher l'endpoint sur VS Code, Claude, Cursor, etc.

✨ Fonctionnalités

🗓️ Calendriers & résultats — matchs passés et à venir, par club ou par équipe.
🏆 Classements — poules complètes avec points, différentiel et forme.
📊 Bilans agrégés — toutes phases confondues en un seul appel.
🔴 Scores live — matchs en cours, mis à jour toutes les 30 s.
🔎 Recherche universelle — clubs, compétitions, salles, engagements.
🚀 Optimisé pour les LLM — réponses agrégées et cache TTL pour réduire le contexte et le nombre d'appels.

🚀 Installation

VS Code / GitHub Copilot

Option recommandée — installer l'extension FFBB Basketball MCP depuis les releases, puis ouvrir Copilot Chat en mode agent.

Alternative sans extension — ➕ Installer FFBB MCP en un clic

Claude Desktop

Option A — Via l'interface de Claude (recommandé, sans prérequis)

Ouvrez les Paramètres de Claude, puis Connecteurs (ou Plugins).
Cliquez sur Ajouter un connecteur personnalisé.
Renseignez l'URL publique https://ffbb.desimone.fr/mcp et validez.

Option B — Via claude_desktop_config.json (nécessite Node.js)

Claude Desktop n'accepte que le transport stdio local : on utilise donc le bridge SSE officiel via npx.

[!WARNING] Prérequis : Node.js (inclut npm et npx). Sans Node.js, privilégiez l'Option A.

{
  "mcpServers": {
    "ffbb": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/client-sse", "https://ffbb.desimone.fr/mcp"]
    }
  }
}

Cursor / autres clients MCP

Configurez un serveur MCP distant :

Champ	Valeur
Type	`Streamable HTTP`
URL	`https://ffbb.desimone.fr/mcp`

Google Antigravity

Configurez directement l'URL distante dans mcp_config.json via la directive native serverUrl :

{
  "mcpServers": {
    "ffbb_mcp": {
      "serverUrl": "https://ffbb.desimone.fr/mcp"
    }
  }
}

🧰 Outils principaux

Outil	Usage
`ffbb_version`	Informations de version et configuration runtime du serveur FFBB MCP.
`ffbb_search`	Recherche FFBB — clubs, compétitions, matchs, salles, tournois, etc.
`ffbb_bilan`	Bilan complet d'une équipe toutes phases confondues en UN seul appel (V/D/N, paniers, phases).
`ffbb_get`	Recupere une ressource FFBB par identifiant.
`ffbb_club`	Outils agrégés club : calendrier (matchs pluriels), équipes engagées ou classement.
`ffbb_lives`	Matchs en cours (scores live, cache 30s). Retourne [] si aucun match.
`ffbb_saisons`	Liste des saisons FFBB. active_only=True pour la saison en cours uniquement.
`ffbb_resolve_team`	Identifie une equipe unique (Pivot central).
`ffbb_team_summary`	Résumé complet et agent-friendly pour une équipe.
`ffbb_last_result`	Dernier résultat d'une équipe précise.
`ffbb_next_match`	Prochain match à jouer pour une équipe précise.
`ffbb_bilan_saison`	Bilan détaillé de la saison pour une équipe précise (toutes phases).
`ffbb_head_to_head`	Compare deux équipes et analyse leurs confrontations directes (H2H).

[!NOTE] Référence complète des paramètres : docs/TOOLS_REFERENCE.md.

🌐 Instance publique

Endpoint MCP (transport Streamable HTTP) :

https://ffbb.desimone.fr/mcp

Endpoint	URL
📊 Dashboard	`https://ffbb.desimone.fr/dashboard`
📈 Métriques	`https://ffbb.desimone.fr/metrics.json`
❤️ Santé	`https://ffbb.desimone.fr/health`

🏗️ Architecture

flowchart LR
    A[Client MCP<br/>Claude · Cursor · Antigravity] -->|Streamable HTTP / Stdio| B[FFBB MCP Server<br/>FastMCP]
    B --> C[Services métier<br/>Cache SWR & Agrégation]
    C --> D[ffbb-data-client<br/>SDK Python]
    D --> E[(API Directus &<br/>Meilisearch FFBB)]

Points clés :

Double transport : Streamable HTTP distant (spec 2025-11-25) ou Stdio local (uvx) ;
SDK Python découplé : Requêtes réseau et parsing Pydantic v2 délégués à ffbb-data-client ;
Agrégation composite : 12 outils optimisés pour réduire les allers-retours et le contexte LLM ;
Cache intelligent & SWR : Stale-While-Revalidate avec TTL par type de donnée (30 s lives, 1 h bilans, 24 h clubs) ;
Observabilité complète : Dashboard HTML, métriques Prometheus, snapshot JSON et healthcheck intégrés.

Détails : docs/ARCHITECTURE.md et docs/PERFORMANCE.md.

💻 Développement local

uv sync --extra dev       # installer les dépendances
uv run ruff format .      # formater
uv run ruff check --fix . # linter
uv run mypy src           # vérifier les types
uv run pytest             # lancer les tests

Voir CONTRIBUTING.md pour les règles de contribution.

🧪 Tests

uv run pytest             # tests unitaires + couverture
uv run pytest tests/      # ciblé

Le pipeline CI (.github/workflows/ci.yml) exécute ruff, mypy, pytest et le contrôle de couverture à chaque push/PR.

📚 Documentation

🤝 Communauté

❓ Dépannage

Symptôme	Cause probable	Solution
`Missing session ID` / `deadline exceeded`	Wrapper `mcp-remote` ou mauvais transport	Utiliser `serverUrl` natif dans `mcp_config.json` (voir Google Antigravity)
Claude Desktop refuse l'URL `http`	Claude Desktop impose `stdio`	Utiliser le bridge `@modelcontextprotocol/client-sse` via `npx` (voir Claude Desktop)
Données live obsolètes	Cache TTL	Attendre le rafraîchissement (≤ 30 s) ou interroger l'endpoint `/health`

🌟 Stargazers & Communauté

Projet non officiel, non affilié à la Fédération Française de BasketBall.

Release files for ffbb-mcp-server 1.9.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ffbb-mcp-server 1.9.0
File	Size	Uploaded
ffbb_mcp_server-1.9.0.tar.gz	163.8 kB	Sep 4, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ffbb-mcp-server 1.9.0
File	Interpreter	ABI	Platform	Reset
ffbb_mcp_server-1.9.0-py3-none-any.whl 124.1 kB Sep 4, 2026	Python 3	none	any	Details

Total release size: 288.0 kB

Release files / ffbb_mcp_server-1.9.0.tar.gz

Download URL	ffbb_mcp_server-1.9.0.tar.gz
Size	163.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`b603d48bb1182c180c8a10296dfb86a205f448451019d27c4da1830ddccf7778`
BLAKE2b-256 checksum How to use checksums	`f0fff7bcfeca6a63547c8b278d14aea9ec3996e21d2971be5c5ec444b385079d`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / ffbb_mcp_server-1.9.0-py3-none-any.whl

Download URL	ffbb_mcp_server-1.9.0-py3-none-any.whl
Size	124.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3870b6985d729094ce9693c775c308188fa1718e96e9aba28d5c0d0228c013af`
BLAKE2b-256 checksum How to use checksums	`47c50575c6d128027e253b45ccca88b2558501ddbac8e9cf274a1ab12e04bf06`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`