VLR MCP

Servidor MCP de Estatísticas da VLR

Um servidor Model Context Protocol (MCP) que fornece ao Claude acesso aos dados de esports de VALORANT da VLR.gg. Construído com FastMCP para fácil integração com o Claude Desktop.

Exemplo de Resposta

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

Recursos

Este servidor MCP fornece as seguintes ferramentas para acessar dados de esports de VALORANT:

Partidas:

• get_upcoming_matches - Obtenha as próximas partidas de VALORANT com nomes de times, eventos e horários
• get_live_matches - Obtenha partidas que estão AO VIVO, com o placar do mapa ao vivo
• get_match_results - Veja resultados recentes de partidas com placares e eventos
• get_match_details - Detalhes completos de uma única partida: veto de mapa, placares por mapa e o placar por jogador (agente, ACS, K/D/A, ADR)

Times:

• get_team_rankings - Acesse os rankings atuais de times (top 20 por região)
• search_team - Consulte o perfil de um time: tag, elenco ativo e equipe técnica
• get_team_matches - Obtenha partidas recentes ou futuras de um time específico
• get_head_to_head - Histórico de confrontos diretos (vitórias/derrotas) e encontros anteriores entre dois times

Eventos:

• get_events - Navegue pelos torneios de VALORANT em andamento, futuros e concluídos
• get_event_details - Premiação, datas, local e times participantes de um único evento

Jogadores e Estatísticas:

• get_player_stats - Obtenha o perfil detalhado do jogador com estatísticas de agentes e métricas de desempenho (suporta filtro de tempo: 30d, 60d, 90d, tudo)
• get_stats_leaderboard - Melhores jogadores por Rating/ACS/K:D em uma região e período (30d/60d/90d), com paginação
• get_agent_stats - Taxas de seleção de agentes por evento e taxas de vitória por mapa em ataque/defesa

Notícias:

• get_news - Artigos recentes de esports de VALORANT (título, resumo, data, autor)

Início Rápido

Instalação

1. Clone este repositório:

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

2. Instale as dependências com uv:

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

Não tem uv? Instale: pip install uv

3. Teste o servidor:

python src/vlr_mcp.py

Integração com o Claude Desktop

Adicione o servidor MCP à configuração do seu Claude Desktop:

Localização do arquivo de configuração:

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

Exemplo rápido de configuração:

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

Para instruções detalhadas de configuração, incluindo WSL, Windows e macOS, consulte SETUP.md

Após adicionar a configuração, reinicie completamente o Claude Desktop e as ferramentas de Estatísticas da VLR estarão disponíveis!

Exemplo de Uso

Após a integração, você pode pedir ao Claude:

Consultas Gerais:

• "Quais partidas de VALORANT estão ao vivo agora?"
• "Quais são as próximas partidas de VALORANT?"
• "Mostre-me resultados recentes de partidas"
• "Detalhe a partida G2 vs Xi Lai Gaming mapa por mapa"
• "Quais são os rankings atuais dos times?"
• "Quais eventos de VALORANT estão acontecendo agora?"
• "Quem está jogando na Esports World Cup 2026 e qual é a premiação?"

Consultas Específicas de Times:

• "Quais foram os últimos 5 jogos da G2 Esports?"
• "Quando o Paper Rex joga novamente?"
• "Quem está no elenco da Sentinels?"
• "Qual é o histórico de confrontos diretos entre Sentinels e LOUD?"

Consultas de Jogadores e Estatísticas:

• "Qual é o agente mais usado pelo aspas nos últimos 90 dias?"
• "Com qual agente o Demon1 tem o melhor K:D?"
• "Quem são os 10 melhores jogadores da UE nos últimos 30 dias?"
• "Quais agentes são mais escolhidos na Esports World Cup 2026?"

Notícias:

• "Quais são as últimas notícias sobre elencos de VALORANT?"
• "Atualize-me sobre as manchetes recentes da VLR"

Referência de Ferramentas

Ferramenta	Descrição
get_upcoming_matches(limit)	Retorna as próximas partidas de VALORANT
get_live_matches()	Retorna partidas atualmente ao vivo, com placar do mapa
get_match_results(limit)	Retorna resultados recentes de partidas com placares
get_match_details(match, players_per_team)	Retorna veto, placares por mapa e placares por jogador de uma partida
get_team_rankings(region)	Retorna os 20 melhores times ranqueados por região
search_team(team_name)	Retorna a tag, o elenco e a equipe técnica de um time
get_team_matches(team_name, limit, match_type)	Retorna partidas específicas de um time (resultados/futuras)
get_head_to_head(team1, team2, limit)	Retorna o histórico de vitórias/derrotas e encontros anteriores entre dois times
get_events(status)	Retorna torneios e eventos de VALORANT
get_event_details(event)	Retorna premiação/datas/local e times participantes de um evento
get_player_stats(player_name, timespan)	Retorna o perfil do jogador com estatísticas detalhadas de agentes (período: 30d, 60d, 90d, tudo)
get_stats_leaderboard(region, timespan, limit, min_rounds, page)	Retorna o ranking de estatísticas de jogadores para uma região/período (30d/60d/90d), paginado
get_agent_stats(event, top)	Retorna taxas de seleção de agentes por evento e taxas de vitória ATQ/DEF por mapa
get_news(limit)	Retorna artigos de notícias recentes de esports de VALORANT

Detalhes das Estatísticas de Jogadores

A ferramenta get_player_stats fornece dados abrangentes de desempenho de agentes, incluindo:

• Agente mais usado - Seleção principal de agente com porcentagem de uso
• Melhor agente em K:D - Agente com maior proporção de abates/mortes
• Agente com maior ACS - Agente com maior pontuação média de combate
• Estatísticas por agente: Rating, ACS, K:D, ADR, KAST, KPR, APR, proporções FK/FD
• Filtro de tempo: Veja estatísticas dos últimos 30/60/90 dias ou de todo o período

Testes

Execute a suíte de testes abrangente para verificar todas as ferramentas:

python test_tools.py

Isso testará:

• Inicialização do servidor MCP
• Todas as ferramentas de extração de dados
• Conexão com a VLR.gg

Estrutura do Projeto

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

Desenvolvimento

Construído com:

• FastMCP - Framework simplificado de servidor MCP
• httpx - Cliente HTTP assíncrono para buscar dados da VLR.gg
• BeautifulSoup4 - Análise de HTML para extrair dados de partidas e times

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou enviar pull requests.

Licença

Consulte o arquivo LICENSE para detalhes.

Aviso Legal

Esta é uma ferramenta não oficial e não é afiliada à VLR.gg ou à Riot Games. Por favor, respeite os termos de serviço e os limites de taxa da VLR.gg.