College Football Data

Accede a estadísticas de fútbol americano universitario desde la API de College Football Data.

GitHub
27
Prueba este MCPPatrocinado

Documentación

Servidor MCP de College Football Data

Una implementación de servidor MCP que proporciona acceso a estadísticas de fútbol americano universitario obtenidas de College Football Data API V2 dentro de Claude Desktop.

Python Version CFBD API Version MIT License smithery badge

Resumen

Este servidor de Protocolo de Contexto de Modelo (MCP) permite a asistentes de IA y aplicaciones:

  • Consultar estadísticas y datos completos de fútbol americano universitario
  • Acceder a resultados de juegos, récords de equipos y estadísticas de jugadores
  • Analizar datos jugada por jugada y resúmenes de series
  • Ver clasificaciones y métricas de probabilidad de victoria
  • Comparar rendimientos de equipos y generar información

Los usuarios pueden ejecutar consultas en lenguaje natural.

Ejemplo de salida

P. ¿Cuál fue la mayor sorpresa entre los juegos de FCS durante la temporada 2014?

R. Déjame ayudarte a encontrar la mayor sorpresa de FCS de 2014. Revisaré los datos de los juegos, centrándome en juegos entre equipos de FCS donde hubiera una brecha significativa en la fuerza de los equipos y un resultado inesperado.

Los datos sugieren que hubo varias sorpresas notables en FCS durante 2014, pero una que destaca fue Eastern Washington derrotando a Washington 52-59 el 6 de septiembre de 2014. Esto fue particularmente significativo porque:

  1. Washington era un equipo de FBS de la conferencia Pac-12
  2. El juego se jugó en el estadio local de Washington (Husky Stadium)
  3. La probabilidad de victoria de Eastern Washington era solo del 1.4% según las estadísticas posteriores al juego.
  4. Los 59 puntos que anotó Eastern Washington fueron la mayor cantidad jamás lograda por un equipo de FCS contra un oponente de Pac-12.
  5. Washington era favorito por múltiples anotaciones antes del juego.

Otras sorpresas notables de FCS de esa temporada incluyeron:

  • North Dakota State derrotando a Iowa State 34-14
  • Bethune-Cookman derrotando a FIU 14-12
  • Northern Iowa casi sorprendiendo a Iowa (perdió 31-23)

Sin embargo, Eastern Washington sobre Washington parece ser la mayor sorpresa de la temporada 2014 de FCS al considerar:

  • La diferencia de divisiones (FCS vs FBS)
  • La calidad del oponente de FBS (conferencia Power 5)
  • El margen de anotación y el rendimiento ofensivo del equipo desfavorecido
  • La importancia histórica como una de las victorias de FCS con mayor puntuación sobre un equipo Power 5
  • El hecho de que ocurrió de visitante en un ambiente hostil

Requisitos previos

Instalación

Instalación mediante Smithery

Para instalar College Football Data Server para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install cfbd --client claude
  1. Clona este repositorio:
git clone https://github.com/yourusername/cfbd-mcp-server
cd cfbd-mcp-server
  1. Crea y activa un entorno virtual:
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Instala las dependencias:
uv pip install -e .
  1. Crea un archivo .env en la raíz del proyecto y agrega tu clave de API:
CFB_API_KEY=your_api_key_here

Instalación manual

  1. Clona este repositorio:
git clone https://github.com/yourusername/cfbd-mcp-server
cd cfbd-mcp-server
  1. Crea y activa un entorno virtual:
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Instala las dependencias:
uv pip install -e .
  1. Crea un archivo .env en la raíz del proyecto y agrega tu clave de API:
CFB_API_KEY=your_api_key_here

Uso

Ejecutar el servidor

Inicia el servidor:

uv run cfbd-mcp-server

Conexión con Claude Desktop

  1. Abre tu configuración de Claude Desktop en:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Agrega la configuración del servidor:

{
    "mcpServers": {
        "cfbd-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/full/path/to/cfbd-mcp-server",
                "run",
                "cfbd-mcp-server"
            ],
            "env": {
                "CFB_API_KEY": "xxx",
                "PATH": "/full/path/to/python"
            }
        }
    }
}
  1. Cierra y reinicia Claude Desktop

Una vez que reinicies, puedes confirmar la instalación haciendo clic en el signo más en la esquina inferior izquierda del cuadro de texto. Si tiene éxito, verás "Add from cfbd-mcp-server" como una de las opciones del menú. Aquí hay una captura de pantalla de ejemplo.

Screenshot of successful install

Actualización después de la instalación

  1. Descarga los archivos actualizados
cd cfbd-mcp-server
git pull
  1. Desinstala el paquete existente:
uv pip uninstall cfbd-mcp-server
  1. Elimina los artefactos de compilación y metadatos existentes

Para Windows:

rmdir /s /q build dist
del /s /q *.egg-info

Para macOS:

rm -rf build dist *.egg-info
  1. Instala el paquete revisado y sus dependencias
uv pip install -e .
uv sync --dev --all-extras

uv run cfbd-mcp-server
  1. Cierra y reinicia Claude Desktop

Características

Recursos

Accede a la documentación del esquema para todos los endpoints:

  • schema://games - Información del juego y puntuaciones
  • schema://records - Récords de temporada de equipos
  • schema://games/teams - Datos detallados de juegos de equipos
  • schema://plays - Información jugada por jugada
  • schema://drives - Resúmenes y resultados de series
  • schema://play/stats - Estadísticas de jugadas individuales
  • schema://rankings - Clasificaciones de equipos en encuestas
  • schema://metrics/wp/pregame - Probabilidades de victoria previas al juego
  • schema://game/box/advanced - Estadísticas avanzadas de box score

Herramientas

Consulta los endpoints directamente:

  • get-games - Recuperar datos de juegos
  • get-records - Obtener récords de equipos
  • get-games-teams - Acceder a estadísticas de juegos de equipos
  • get-plays - Consultar datos jugada por jugada
  • get-drives - Analizar información de series
  • get-play-stats - Ver estadísticas de jugadas
  • get-rankings - Consultar clasificaciones de equipos
  • get-pregame-win-probability - Ver probabilidades de victoria
  • get-advanced-box-score - Acceder a estadísticas y análisis detallados de juegos

Indicaciones

Plantillas de análisis predefinidas:

  • analyze-game - Obtener análisis detallado de un juego específico
  • analyze-team - Análisis integral de un solo equipo
  • analyze-trends - Analizar tendencias a lo largo de una temporada
  • compare-teams - Comparar el rendimiento de dos equipos
  • analyze-rivalry - Analizar enfrentamientos históricos de rivalidad

Límites de API

La API de College Football Data es gratuita pero tiene límites de velocidad:

  • Nivel gratuito: solicitudes limitadas por minuto
  • Suscriptores de CFBD Patreon obtienen límites más altos
  • Usa patrones de consulta eficientes para evitar alcanzar los límites
  • Maneja los errores de límite de velocidad con elegancia

Desarrollo

Estructura del proyecto

cfbd-mcp-server/
├── README.md
├── pyproject.toml
└── src/
    └── cfbd_mcp_server/
        ├── .env
        ├── __init__.py
        ├── cfbd_schema.py
        ├── schema_helpers.py
        └── server.py

Configuración para el desarrollo

  1. Clona el repositorio
  2. Instala las dependencias de desarrollo:
uv pip install -e ".[dev]"
  1. Ejecuta las pruebas:
pytest

Contribuciones

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Realiza tus cambios
  4. Haz push a tu fork
  5. Envía una solicitud de extracción

Solución de problemas

Problemas comunes

  1. Errores de clave de API

    • Verifica que tu clave de API esté configurada correctamente en los archivos .env y claude_desktop_config.json
    • Comprueba que la clave sea válida en collegefootballdata.com

  2. Límite de velocidad

    • Espacia las solicitudes cuando sea posible
    • Considera la suscripción a Patreon para límites más altos
    • Implementa caché para datos de acceso frecuente

  3. Problemas de conexión

    • Verifica la conectividad a Internet
    • Comprueba el estado de la API en collegefootballdata.com
    • Asegúrate de manejar errores adecuadamente en tu código

Obtener ayuda

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Agradecimientos