Labsco
OkeahDavid logo

VLR MCP

from OkeahDavid

MCP server for accessing VLR.gg VALORANT esports data

🔥🔥🔥✓ VerifiedFreeQuick setup
#scraping#git#maps

VLR Stats MCP

A Model Context Protocol (MCP) server that provides Claude with access to VLR.gg VALORANT esports data. Built with FastMCP for easy integration with Claude Desktop.

image

Sample Response

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

Features

This MCP server provides the following tools to access VALORANT esports data:

Matches:

  • get_upcoming_matches - Get upcoming VALORANT matches with team names, events, and timing
  • get_live_matches - Get matches that are currently LIVE, with the live map score
  • get_match_results - View recent match results with scores and events
  • get_match_details - Full detail for a single match: map veto, per-map scores, and the per-player scoreboard (agent, ACS, K/D/A, ADR)

Teams:

  • get_team_rankings - Access current team rankings (top 20 by region)
  • search_team - Look up a team's profile: tag, active roster, and staff
  • get_team_matches - Get recent or upcoming matches for a specific team
  • get_head_to_head - Head-to-head W-L record and past meetings between two teams

Events:

  • get_events - Browse ongoing, upcoming, and completed VALORANT tournaments
  • get_event_details - Prize pool, dates, location, and participating teams for a single event

Players & Stats:

  • get_player_stats - Get detailed player profile with agent statistics and performance metrics (supports time filtering: 30d, 60d, 90d, all)
  • get_stats_leaderboard - Top players by Rating/ACS/K:D across a region and time window (30d/60d/90d), with paging
  • get_agent_stats - Per-event agent pick rates and per-map attack/defense win rates

News:

  • get_news - Recent VALORANT esports articles (title, blurb, date, author)

Tools Reference

ToolDescription
get_upcoming_matches(limit)Returns upcoming VALORANT matches
get_live_matches()Returns matches that are currently live, with map score
get_match_results(limit)Returns recent match results with scores
get_match_details(match, players_per_team)Returns veto, per-map scores, and per-player scoreboards for a match
get_team_rankings(region)Returns top 20 ranked teams by region
search_team(team_name)Returns a team's tag, roster, and staff
get_team_matches(team_name, limit, match_type)Returns team-specific matches (results/upcoming)
get_head_to_head(team1, team2, limit)Returns the W-L record and past meetings between two teams
get_events(status)Returns VALORANT tournaments and events
get_event_details(event)Returns prize/dates/location and participating teams for an event
get_player_stats(player_name, timespan)Returns player profile with detailed agent statistics (timespan: 30d, 60d, 90d, all)
get_stats_leaderboard(region, timespan, limit, min_rounds, page)Returns the player stats leaderboard for a region/window (30d/60d/90d), paged
get_agent_stats(event, top)Returns per-event agent pick rates and per-map ATK/DEF win rates
get_news(limit)Returns recent VALORANT esports news articles

Player Stats Details

The get_player_stats tool provides comprehensive agent performance data including:

  • Most used agent - Primary agent pick with usage percentage
  • Best K:D agent - Agent with highest kill/death ratio
  • Highest ACS agent - Agent with highest average combat score
  • Per-agent statistics: Rating, ACS, K:D, ADR, KAST, KPR, APR, FK/FD ratios
  • Time filtering: View stats for last 30/60/90 days or all time

Testing

Run the comprehensive test suite to verify all tools:

python test_tools.py

This will test:

  • MCP server initialization
  • All data-scraping tools
  • Connection to VLR.gg

Project Structure

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

Development

Built with:

  • FastMCP - Simplified MCP server framework
  • httpx - Async HTTP client for fetching VLR.gg data
  • BeautifulSoup4 - HTML parsing for extracting match and team data

Disclaimer

This is an unofficial tool and is not affiliated with VLR.gg or Riot Games. Please respect VLR.gg's terms of service and rate limits.