NBA Player Stats

Proporciona estadísticas completas de jugadores de la NBA desde basketball-reference.com, incluyendo estadísticas de carrera, comparaciones de temporadas y métricas avanzadas.

GitHub
3
Prueba este MCPPatrocinado

Documentación

NBA Player Stats MCP Server

Un servidor especializado del Model Context Protocol (MCP) que proporciona estadísticas completas de jugadores de la NBA desde basketball-reference.com. Este servidor se especializa en ofrecer estadísticas detalladas de jugadores, incluyendo estadísticas de carrera, comparaciones de temporadas, métricas avanzadas, estadísticas de tiro y más.

Tabla de Contenidos

Características

Este servidor MCP proporciona herramientas especializadas de estadísticas de jugadores de la NBA en tres niveles de profundidad:

Nivel 1: Estadísticas Básicas (Herramientas 1-10)

  • Estadísticas de Carrera: Estadísticas completas de carrera con desgloses temporada por temporada
  • Estadísticas de Temporada: Estadísticas detalladas de temporadas específicas, incluyendo playoffs
  • Promedios por Partido: Estadísticas tradicionales por partido
  • Estadísticas Totales: Totales de temporada y carrera (no promedios)
  • Por 36 Minutos: Estadísticas ajustadas al ritmo por 36 minutos
  • Métricas Avanzadas: PER, TS%, WS, BPM, VORP y otras métricas de eficiencia
  • Comparaciones de Jugadores: Comparaciones lado a lado entre dos jugadores
  • Desgloses de Tiro: Porcentajes de tiro detallados y estadísticas de volumen
  • Rendimiento en Playoffs: Estadísticas completas de playoffs con comparaciones con la temporada regular
  • Momentos Destacados de Carrera: Mejores temporadas, hitos y logros

Nivel 2: Análisis Profundo (Herramientas 11-17)

  • Registros de Partidos: Estadísticas partido a partido para análisis detallado
  • Consultas de Estadísticas Específicas: Obtén estadísticas individuales para cualquier temporada (por ejemplo, "el 3P% de Steph en 2018")
  • Premios y Votaciones: Posiciones en votaciones de MVP, DPOY y otros premios
  • Estadísticas vs. Equipos: Rendimiento de carrera contra equipos específicos
  • Desgloses Mensuales: Rendimiento desglosado por mes
  • Estadísticas en Momentos Decisivos: Rendimiento en partidos cerrados y situaciones de presión
  • Detalles de Playoffs: Rendimiento en playoffs año por año

Nivel 3: Análisis Ultra Profundo (Herramientas 18-23)

  • Tendencias de Carrera: Análisis de progresión y declive año tras año
  • Máximos en Partidos: Máximos de carrera, partidos de 40+ puntos, triples-dobles
  • Desgloses Situacionales: Local/visitante, días de descanso, situaciones de victoria/derrota
  • Estadísticas por Cuarto: Especialización en el 4º cuarto y rendimiento en momentos decisivos
  • Seguimiento de Hitos: Progreso hacia récords con proyecciones
  • Clasificaciones Históricas: Posición de los jugadores en la historia de la NBA

Características Adicionales

  • Fotos de Jugadores: URLs de fotos de jugadores de basketball-reference.com
  • Múltiples Tipos de Estadísticas: PER_GAME, TOTALS, PER_MINUTE, PER_POSS, ADVANCED
  • Datos Históricos: Acceso a temporadas históricas y progresiones de carrera
  • 23 Herramientas en Total: Cobertura completa de cualquier consulta concebible de estadísticas de jugadores

Inicio Rápido

Instalar desde PyPI

pip install nba-player-stats-mcp

Instalar desde el Código Fuente

  1. Clona el repositorio:
git clone https://github.com/ziyadmir/nba-player-stats-mcp
cd nba-player-stats-mcp
  1. Instala las dependencias:
pip install -r requirements.txt

Ejecutar el Servidor

# If installed from PyPI
nba-player-stats-server

# If running from source
python src/server.py

Configurar Claude Desktop

{
  "mcpServers": {
    "nba-player-stats": {
      "command": "python",
      "args": ["path/to/basketball/src/server.py"],
      "cwd": "path/to/basketball"
    }
  }
}

Instalación

Requisitos Previos

  • Python 3.8 o superior
  • Gestor de paquetes pip

Instalar desde PyPI

La forma más fácil de instalar el Servidor de Estadísticas de Jugadores de la NBA:

pip install nba-player-stats-mcp

Instalar desde el Código Fuente

Para desarrollo o para obtener los últimos cambios:

  1. Clona el repositorio:
git clone https://github.com/ziyadmir/nba-player-stats-mcp
cd nba-player-stats-mcp
  1. Crea un entorno virtual (recomendado):
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Instala en modo de desarrollo:
pip install -e .
# Or with development dependencies
pip install -e ".[dev]"

Uso

Iniciar el Servidor

# If installed from PyPI
nba-player-stats-server

# If running from source
python src/server.py

Ejemplos de Uso en Python

# Import the fix first
import fix_basketball_reference
from basketball_reference_scraper.players import get_stats

# Get LeBron's career per-game stats
stats = get_stats('LeBron James', stat_type='PER_GAME', ask_matches=False)

# Get specific season
stats_2023 = stats[stats['SEASON'] == '2022-23']

# Get playoff stats
playoff_stats = get_stats('LeBron James', stat_type='PER_GAME', playoffs=True, ask_matches=False)

Consulta example_usage.py para ver ejemplos más completos.

Herramientas Disponibles

1. get_player_career_stats

Obtén estadísticas completas de carrera para un jugador de la NBA.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador (por ejemplo, "LeBron James")
  • stat_type (cadena, opcional): Tipo de estadísticas - "PER_GAME", "TOTALS", "PER_MINUTE", "PER_POSS", "ADVANCED"

2. get_player_season_stats

Obtén estadísticas para una temporada específica.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • season (entero, obligatorio): Año de la temporada (por ejemplo, 2023 para 2022-23)
  • stat_type (cadena, opcional): Tipo de estadísticas
  • include_playoffs (booleano, opcional): Incluir estadísticas de playoffs si están disponibles

3. get_player_advanced_stats

Obtén estadísticas avanzadas (PER, TS%, WS, BPM, VORP, etc.).

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • season (entero, opcional): Temporada específica, o None para todas las temporadas

4. get_player_per36_stats

Obtén estadísticas por 36 minutos (ajustadas al ritmo).

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • season (entero, opcional): Temporada específica, o None para todas las temporadas

5. compare_players

Compara estadísticas entre dos jugadores de la NBA.

Parámetros:

  • player1_name (cadena, obligatorio): Nombre del primer jugador
  • player2_name (cadena, obligatorio): Nombre del segundo jugador
  • stat_type (cadena, opcional): Tipo de estadísticas a comparar
  • season (entero, opcional): Temporada específica, o None para comparación de carrera

6. get_player_shooting_splits

Obtén estadísticas de tiro detalladas y desgloses.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • season (entero, opcional): Temporada específica, o None para estadísticas de carrera

7. get_player_totals

Obtén estadísticas totales (no promedios).

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • season (entero, opcional): Temporada específica, o None para totales de carrera

8. get_player_playoff_stats

Obtén estadísticas de playoffs con comparación con la temporada regular.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • stat_type (cadena, opcional): Tipo de estadísticas

9. get_player_headshot_url

Obtén la URL de la foto de basketball-reference.com.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador

10. get_player_career_highlights

Obtén momentos destacados y logros de carrera.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador

Nivel 2: Herramientas de Análisis Profundo

11. get_player_game_log

Obtén estadísticas partido a partido para una temporada específica.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • season (entero, obligatorio): Año de la temporada (por ejemplo, 2024)
  • playoffs (booleano, opcional): Si se deben obtener los registros de partidos de playoffs
  • date_from (cadena, opcional): Fecha de inicio en formato 'YYYY-MM-DD'
  • date_to (cadena, opcional): Fecha de fin en formato 'YYYY-MM-DD'

12. get_player_specific_stat

Obtén una estadística específica para un jugador en una temporada determinada. Perfecto para responder preguntas como "¿Cuál fue el 3P% de Steph en 2018?"

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • stat_name (cadena, obligatorio): La estadística específica (por ejemplo, "PTS", "3P%", "PER")
  • season (entero, obligatorio): Año de la temporada

13. get_player_vs_team_stats

Obtén estadísticas de carrera contra un equipo específico.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • team_abbreviation (cadena, obligatorio): Código del equipo (por ejemplo, "GSW", "LAL")
  • stat_type (cadena, opcional): Tipo de estadísticas

14. get_player_awards_voting

Obtén premios e historial de votaciones.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • award_type (cadena, opcional): "MVP", "DPOY", "ROY", "SMOY", "MIP"

15. get_player_monthly_splits

Obtén estadísticas desglosadas por mes.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • season (entero, obligatorio): Año de la temporada
  • month (cadena, opcional): Mes específico o None para todos

16. get_player_clutch_stats

Obtén rendimiento en situaciones decisivas.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • season (entero, opcional): Temporada específica o None para la carrera

17. get_player_playoffs_by_year

Obtén estadísticas detalladas de playoffs para un año específico.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • season (entero, obligatorio): Año de la temporada

Nivel 3: Herramientas de Análisis Ultra Profundo

18. get_player_career_trends

Analiza tendencias y progresión de carrera, incluyendo cambios año tras año y patrones de declive/mejora.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • stat_name (cadena, opcional): La estadística para analizar tendencias (predeterminado: "PTS")
  • window_size (entero, opcional): Años para el promedio móvil (predeterminado: 3)

19. get_player_game_highs

Obtén partidos con máximos de carrera y actuaciones históricas (partidos de 40+ puntos, partidos de 50+ puntos, triples-dobles).

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • threshold_points (entero, opcional): Umbral de puntos para partidos de alta anotación (predeterminado: 40)
  • include_triple_doubles (booleano, opcional): Si se deben estimar partidos con triples-dobles

20. get_player_situational_splits

Obtén desgloses de rendimiento situacional, incluyendo local/visitante, días de descanso y situaciones de victoria/derrota.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • season (entero, opcional): Temporada específica o None para la carrera
  • split_type (cadena, opcional): "home_away", "rest_days", "monthly", "win_loss"

21. get_player_quarter_stats

Obtén rendimiento cuarto por cuarto, especialmente estadísticas del 4º cuarto y tiempo extra.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • season (entero, opcional): Temporada específica o None para la carrera
  • quarter (cadena, opcional): "1st", "2nd", "3rd", "4th", "OT" o "all"

22. get_player_milestone_tracker

Sigue el progreso hacia hitos de carrera con proyecciones de logro.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • milestone_type (cadena, opcional): "points", "assists", "rebounds", "3pm", "games"

23. get_player_rankings

Obtén clasificaciones históricas para un jugador en varias categorías.

Parámetros:

  • player_name (cadena, obligatorio): El nombre del jugador
  • category (cadena, opcional): "points", "assists", "rebounds", "3pm", "steals", "blocks"

Ejemplos

Aquí hay algunas preguntas de ejemplo que este servidor MCP puede responder:

Consultas Básicas (Nivel 1)

  1. Resumen de Carrera: "¿Cuáles son las estadísticas de carrera de LeBron James?"
  2. Comparación de Temporadas: "¿Cómo se desempeñó Stephen Curry en la temporada 2016?"
  3. Comparación de Jugadores: "Compara las estadísticas de carrera de Michael Jordan y LeBron James"
  4. Análisis de Tiro: "¿Cuáles son los porcentajes de tiro de carrera de Steph Curry?"
  5. Métricas Avanzadas: "¿Cuál fue el PER de Nikola Jokić en 2023?"
  6. Rendimiento en Playoffs: "¿Cómo se comparan las estadísticas de playoffs de Kawhi Leonard con las de temporada regular?"
  7. Hitos de Carrera: "¿Cuáles son los momentos destacados de la carrera de Kareem Abdul-Jabbar?"
  8. Estadísticas por 36 Minutos: "¿Cuáles son las estadísticas por 36 minutos de Giannis Antetokounmpo?"

Consultas de Análisis Profundo (Nivel 2)

  1. Estadística Específica: "¿Cuál fue el porcentaje de triples de Steph Curry en 2018?"
  2. Consulta de Puntos: "¿Cuántos puntos promedió Stephen Curry en 2024?"
  3. Premios: "¿En qué posición terminó LeBron James en la votación del MVP en 2020?"
  4. Registros de Partidos: "Muéstrame el registro de partidos de Damian Lillard en los playoffs de 2021"
  5. Vs. Equipo: "¿Cuáles son las estadísticas de carrera de Kevin Durant contra los Lakers?"
  6. Mensual: "¿Cómo se desempeñó Jayson Tatum en diciembre de 2023?"
  7. Momentos Decisivos: "¿Cuáles son las estadísticas en momentos decisivos de Kyrie Irving en su carrera?"
  8. Año de Playoffs: "¿Cómo se desempeñó Jimmy Butler en los playoffs de 2020?"

Consultas de análisis ultraprofundo (Capa 3)

  1. Tendencias de carrera: "¿Está LeBron James en declive con la edad?"
  2. Juegos históricos: "¿Cuántos juegos de 40 puntos tiene Kevin Durant?"
  3. Local/Visitante: "¿Cómo se desempeña Joel Embiid en casa vs. fuera?"
  4. 4to cuarto: "¿Cuál es el promedio de anotación de Luka Dončić en los 4tos cuartos?"
  5. Seguimiento de hitos: "¿Cuándo superará LeBron los 40,000 puntos?"
  6. Clasificaciones históricas: "¿Dónde se ubica Steph Curry en la clasificación histórica de triples anotados?"
  7. Situacional: "¿Cómo se desempeña Giannis en partidos consecutivos?"
  8. Desglose por cuarto: "¿Qué porcentaje de los puntos de Dame vienen en el 4to?"

Explicaciones de tipos de estadísticas

  • PER_GAME: Promedios tradicionales por juego (puntos, rebotes, asistencias, etc.)
  • TOTALS: Estadísticas totales para una temporada o carrera
  • PER_MINUTE: Estadísticas por 36 minutos (normalizadas por tiempo de juego)
  • PER_POSS: Estadísticas por 100 posesiones (normalizadas por ritmo)
  • ADVANCED: Métricas avanzadas (PER, TS%, WS, BPM, VORP, etc.)

Glosario de estadísticas clave

  • PER: Índice de eficiencia del jugador
  • TS%: Porcentaje de tiro real
  • WS: Victorias compartidas
  • BPM: Box Plus/Minus
  • VORP: Valor sobre jugador de reemplazo
  • eFG%: Porcentaje de tiro efectivo
  • USG%: Tasa de uso
  • ORtg: Rating ofensivo (puntos por 100 posesiones)
  • DRtg: Rating defensivo (puntos permitidos por 100 posesiones)
  • 3P%: Porcentaje de tiros de tres puntos
  • FT%: Porcentaje de tiros libres
  • AST%: Porcentaje de asistencias
  • REB%: Porcentaje de rebotes

Correcciones del scraper de Basketball Reference

Importante: La biblioteca basketball_reference_scraper tiene problemas de compatibilidad con la estructura actual del sitio web basketball-reference.com. Este servidor incluye correcciones automáticas para estos problemas.

Problemas corregidos

  1. Cambios en IDs de tablas: Basketball Reference actualizó sus IDs de tablas HTML

    • per_game → per_game_stats
    • totals → totals_stats
    • per_minute → per_minute_stats

  2. Compatibilidad con Pandas: Se corrigieron las advertencias de obsolescencia con pd.read_html()

  3. Manejo de errores: Se mejoró el manejo de datos faltantes y casos límite

Las correcciones se aplican automáticamente cuando el servidor se inicia mediante el módulo fix_basketball_reference.py.

Detalles completos de la corrección

La corrección implica actualizar el archivo basketball_reference_scraper/players.py:

  1. Agregar importación de StringIO (después de la importación de BeautifulSoup):

    from io import StringIO

  2. Actualizar el mapeo de IDs de tabla (en la función get_stats):

    # Map old table IDs to new ones
table_id_map = {
    'per_game': 'per_game_stats',
    'totals': 'totals_stats',
    'per_minute': 'per_minute_stats',
    'per_poss': 'per_poss_stats',
    'advanced': 'advanced'
}

  3. Corregir la obsolescencia de pandas read_html:

    # Replace: df = pd.read_html(table)[0]
df = pd.read_html(StringIO(table))[0]

  4. Manejar la fila de carrera faltante:

    career_rows = df[df['SEASON']=='Career'].index
if len(career_rows) > 0:
    career_index = career_rows[0]
    # ... rest of logic

Para contribuir con estas correcciones a la biblioteca original, consulta la sección Contribuciones.

Guía de desarrollo

Configuración del entorno de desarrollo

  1. Crear entorno virtual:

    python -m venv venv
source venv/bin/activate

  2. Instalar dependencias:

    pip install -r requirements.txt

Pruebas

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test
pytest tests/test_integration.py -v

Pruebas manuales

Prueba el módulo de corrección:

python example_usage.py

Casos de prueba comunes

  1. Variaciones de nombres de jugadores:

    • Coincidencia exacta: "LeBron James" ✓
    • Sensibilidad a mayúsculas: "lebron james" ✗
    • Nombres parciales: "LeBron" ✗

  2. Casos límite:

    • Jugadores retirados
    • Jugadores sin experiencia en playoffs
    • Jugadores históricos (pre-1973 para estadísticas avanzadas)

Directrices de estilo de código

  1. Estilo de Python: Sigue PEP 8
  2. Manejo de errores: Siempre captura excepciones específicas
  3. Procesamiento de datos: Verifica resultados vacíos antes de acceder

Extensión del servidor

Para agregar nuevas herramientas:

  1. Crea la función en server.py:

    @mcp.tool()
async def get_player_new_stat(
    player_name: str,
    **kwargs
) -> Dict[str, Any]:
    """Tool description"""
    try:
        # Implementation
        pass
    except Exception as e:
        logger.error(f"Error: {e}")
        return {"error": str(e)}

  2. Prueba exhaustivamente con varios jugadores

  3. Actualiza este README con la documentación de la nueva herramienta

Problemas conocidos

Funciones que funcionan ✅

  • Todas las herramientas de estadísticas de jugadores funcionan correctamente con las correcciones aplicadas
  • Las URLs de las fotos de los jugadores funcionan de manera confiable

Limitaciones ⚠️

  1. Nombres de jugadores: Deben coincidir exactamente con el formato de basketball-reference.com

    • ✓ "LeBron James"
    • ✗ "Lebron" o "lebron james"

  2. Datos históricos: Algunas funciones pueden tener datos limitados para temporadas antiguas

    • Estadísticas avanzadas no disponibles antes de 1973-74
    • Algunas estadísticas de tiro faltan para carreras tempranas

  3. Limitaciones de la biblioteca: La biblioteca subyacente basketball_reference_scraper tiene:

    • Sin mantenimiento activo
    • Manejo de errores inconsistente
    • Documentación limitada

Solución de problemas

Error "No se encontraron tablas"

  • Causa: La estructura del sitio web cambió
  • Solución: Se aplica automáticamente mediante fix_basketball_reference.py

Jugador no encontrado

  • Causa: Formato de nombre incorrecto
  • Solución: Usa nombres exactos de basketball-reference.com

Resultados vacíos

  • Causa: El jugador no tiene estadísticas para el tipo/temporada solicitado
  • Solución: Verifica el rango de carrera del jugador y la disponibilidad de estadísticas

Pruebas

Ejecuta la suite de pruebas:

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

Contribuciones

  1. Haz un fork del repositorio
  2. Crea tu rama de características (git checkout -b feature/amazing-feature)
  3. Haz commit de tus cambios (git commit -m 'Add some amazing feature')
  4. Haz push a la rama (git push origin feature/amazing-feature)
  5. Abre un Pull Request

Contribuir correcciones a basketball_reference_scraper

Para contribuir con nuestras correcciones a la biblioteca original:

  1. Fork: https://github.com/vishaalagartha/basketball_reference_scraper
  2. Aplica los cambios de fix_basketball_reference.py
  3. Prueba exhaustivamente con varios jugadores
  4. Envía un PR: "Fix table parsing for updated basketball-reference.com structure"

Registro de cambios

Versión 0.3.0 (Última)

  • Se agregaron herramientas de análisis ultraprofundo de la Capa 3 (6 nuevas herramientas)
  • Análisis de tendencias de carrera con progresión año tras año
  • Máximos de juego y seguimiento de hitos (juegos de 40+ puntos, triples-dobles)
  • Divisiones situacionales (local/visitante, días de descanso, victorias/derrotas)
  • Análisis de rendimiento cuarto por cuarto
  • Proyecciones de hitos y clasificaciones históricas
  • Ahora incluye 23 herramientas en total en 3 capas

Versión 0.2.0

  • Se agregaron herramientas de análisis profundo de la Capa 2 (7 nuevas herramientas)
  • Registros de juegos y consultas de estadísticas específicas
  • Soporte para premios e historial de votaciones
  • Estadísticas de enfrentamientos de equipos
  • Divisiones mensuales y temporales
  • Métricas de rendimiento en momentos decisivos
  • Análisis mejorado de playoffs año por año

Versión 0.1.0

  • Lanzamiento inicial con 10 herramientas principales de estadísticas de jugadores
  • Correcciones de compatibilidad con basketball-reference.com
  • Estadísticas de carrera, temporada y avanzadas

Licencia

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

Agradecimientos

Soporte

Para problemas y solicitudes de funciones, utiliza el rastreador de problemas de GitHub.