VLR MCP

Servidor MCP de Estadísticas de VLR

Un servidor de Model Context Protocol (MCP) que proporciona a Claude acceso a los datos de esports de VALORANT de VLR.gg. Construido con FastMCP para una fácil integración con Claude Desktop.

Respuesta de Ejemplo

Player Profile: aspas
Timespan: ALL
Current Team: MIBR
Team Page: https://www.vlr.gg/team/7386/mibr
Profile: https://www.vlr.gg/player/8480/aspas

--- Agent Statistics (ALL) ---

1. Jett - (226) 51%
   Rating: 1.26 | ACS: 249.8 | K:D: 1.45
   Rounds: 4749 | ADR: 158.8 | KAST: 75%
   KPR: 0.91 | APR: 0.15 | FK/FD: 0.19/0.11
   Kills: 4303 | Deaths: 2977

2. Raze - (112) 26%
   Rating: 1.19 | ACS: 247.0 | K:D: 1.25
   Rounds: 2332 | ADR: 164.2 | KAST: 76%
   KPR: 0.87 | APR: 0.20 | FK/FD: 0.16/0.11
   Kills: 2018 | Deaths: 1614

Características

Este servidor MCP proporciona las siguientes herramientas para acceder a los datos de esports de VALORANT:

Partidos:

• get_upcoming_matches - Obtén los próximos partidos de VALORANT con nombres de equipos, eventos y horarios
• get_live_matches - Obtén los partidos que están actualmente EN VIVO, con el marcador del mapa en vivo
• get_match_results - Consulta los resultados de partidos recientes con puntuaciones y eventos
• get_match_details - Detalle completo de un solo partido: veto de mapas, puntuaciones por mapa y la tabla de puntuaciones por jugador (agente, ACS, K/D/A, ADR)

Equipos:

• get_team_rankings - Accede a las clasificaciones actuales de equipos (top 20 por región)
• search_team - Busca el perfil de un equipo: etiqueta, plantilla activa y personal
• get_team_matches - Obtén partidos recientes o próximos de un equipo específico
• get_head_to_head - Registro de victorias-derrotas cara a cara y enfrentamientos pasados entre dos equipos

Eventos:

• get_events - Explora torneos de VALORANT en curso, próximos y finalizados
• get_event_details - Premio acumulado, fechas, ubicación y equipos participantes de un solo evento

Jugadores y Estadísticas:

• get_player_stats - Obtén el perfil detallado del jugador con estadísticas de agentes y métricas de rendimiento (admite filtrado por tiempo: 30d, 60d, 90d, todo)
• get_stats_leaderboard - Mejores jugadores por Rating/ACS/K:D en una región y ventana de tiempo (30d/60d/90d), con paginación
• get_agent_stats - Tasas de selección de agentes por evento y tasas de victoria por mapa en ataque/defensa

Noticias:

• get_news - Artículos recientes de esports de VALORANT (título, resumen, fecha, autor)

Inicio Rápido

Instalación

1. Clona este repositorio:

git clone <your-repo-url>
cd vlr-stats-mcp

2. Instala las dependencias con uv:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

¿No tienes uv? Instálalo: pip install uv

3. Prueba el servidor:

python src/vlr_mcp.py

Integración con Claude Desktop

Añade el servidor MCP a tu configuración de Claude Desktop:

Ubicación del archivo de configuración:

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

Ejemplo rápido de configuración:

{
  "mcpServers": {
    "vlr-stats": {
      "command": "python",
      "args": ["/absolute/path/to/vlr-stats-mcp/src/vlr_mcp.py"]
    }
  }
}

Para instrucciones detalladas de configuración, incluyendo configuraciones de WSL, Windows y macOS, consulta SETUP.md

Después de añadir la configuración, reinicia Claude Desktop por completo y ¡las herramientas de Estadísticas de VLR estarán disponibles!

Ejemplo de Uso

Una vez integrado, puedes preguntar a Claude:

Consultas Generales:

• "¿Qué partidos de VALORANT están en vivo ahora mismo?"
• "¿Cuáles son los próximos partidos de VALORANT?"
• "Muéstrame los resultados de partidos recientes"
• "Desglosa el partido de G2 vs Xi Lai Gaming mapa por mapa"
• "¿Cuáles son las clasificaciones actuales de equipos?"
• "¿Qué eventos de VALORANT están ocurriendo ahora?"
• "¿Quién juega en la Copa del Mundo de Esports 2026 y cuál es el premio acumulado?"

Consultas Específicas de Equipos:

• "¿Cuáles son los últimos 5 partidos de G2 Esports?"
• "¿Cuándo juega Paper Rex la próxima vez?"
• "¿Quién está en la plantilla de Sentinels?"
• "¿Cuál es el registro cara a cara entre Sentinels y LOUD?"

Consultas de Jugadores y Estadísticas:

• "¿Cuál es el agente más usado de aspas en los últimos 90 días?"
• "¿Con qué agente tiene Demon1 el mejor K:D?"
• "¿Quiénes son los 10 mejores jugadores en la UE durante los últimos 30 días?"
• "¿Qué agentes son los más seleccionados en la Copa del Mundo de Esports 2026?"

Noticias:

• "¿Cuál es la última noticia sobre plantillas de VALORANT?"
• "Ponme al día con los titulares recientes de VLR"

Referencia de Herramientas

Herramienta	Descripción
get_upcoming_matches(limit)	Devuelve los próximos partidos de VALORANT
get_live_matches()	Devuelve los partidos actualmente en vivo, con marcador de mapa
get_match_results(limit)	Devuelve los resultados de partidos recientes con puntuaciones
get_match_details(match, players_per_team)	Devuelve veto, puntuaciones por mapa y tablas de puntuación por jugador de un partido
get_team_rankings(region)	Devuelve los 20 mejores equipos clasificados por región
search_team(team_name)	Devuelve la etiqueta, plantilla y personal de un equipo
get_team_matches(team_name, limit, match_type)	Devuelve partidos específicos de un equipo (resultados/próximos)
get_head_to_head(team1, team2, limit)	Devuelve el registro de victorias-derrotas y enfrentamientos pasados entre dos equipos
get_events(status)	Devuelve torneos y eventos de VALORANT
get_event_details(event)	Devuelve premio/fechas/ubicación y equipos participantes de un evento
get_player_stats(player_name, timespan)	Devuelve el perfil del jugador con estadísticas detalladas de agentes (periodo: 30d, 60d, 90d, todo)
get_stats_leaderboard(region, timespan, limit, min_rounds, page)	Devuelve la tabla de clasificación de estadísticas de jugadores para una región/ventana (30d/60d/90d), paginada
get_agent_stats(event, top)	Devuelve tasas de selección de agentes por evento y tasas de victoria ATQ/DEF por mapa
get_news(limit)	Devuelve artículos de noticias recientes de esports de VALORANT

Detalles de Estadísticas de Jugadores

La herramienta get_player_stats proporciona datos completos de rendimiento de agentes, incluyendo:

• Agente más usado - Selección principal de agente con porcentaje de uso
• Agente con mejor K:D - Agente con la mayor proporción de bajas/muertes
• Agente con mayor ACS - Agente con la puntuación media de combate más alta
• Estadísticas por agente: Rating, ACS, K:D, ADR, KAST, KPR, APR, proporciones FK/FD
• Filtrado por tiempo: Consulta estadísticas de los últimos 30/60/90 días o de todo el tiempo

Pruebas

Ejecuta la suite de pruebas completa para verificar todas las herramientas:

python test_tools.py

Esto probará:

• Inicialización del servidor MCP
• Todas las herramientas de extracción de datos
• Conexión con VLR.gg

Estructura del Proyecto

src/
  vlr_mcp.py           # Main MCP server (composes tool modules)
  config.py            # Shared config + fetch/cache/search helpers
  tools/
    matches.py         # get_upcoming_matches, get_live_matches, get_match_results, get_match_details
    teams.py           # get_team_rankings, search_team, get_team_matches, get_head_to_head
    players.py         # get_player_stats
    events.py          # get_events, get_event_details
    stats.py           # get_stats_leaderboard
    agents.py          # get_agent_stats
    news.py            # get_news
test_tools.py          # Comprehensive test suite

Desarrollo

Construido con:

• FastMCP - Marco simplificado de servidor MCP
• httpx - Cliente HTTP asíncrono para obtener datos de VLR.gg
• BeautifulSoup4 - Análisis de HTML para extraer datos de partidos y equipos

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en abrir issues o enviar pull requests.

Licencia

Consulta el archivo LICENSE para más detalles.

Aviso Legal

Esta es una herramienta no oficial y no está afiliada con VLR.gg ni Riot Games. Por favor, respeta los términos de servicio y los límites de tasa de VLR.gg.