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.

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)

Quick Start

Installation

Clone this repository:

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

Install dependencies with uv:

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

Don't have uv? Install it: pip install uv

Test the server:

python src/vlr_mcp.py

Claude Desktop Integration

Add the MCP server to your Claude Desktop configuration:

Configuration file location:

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

Quick config example:

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

For detailed setup instructions including WSL, Windows, and macOS configurations, see SETUP.md

After adding the configuration, restart Claude Desktop completely and the VLR Stats tools will be available!

Example Usage

Once integrated, you can ask Claude:

General Queries:

"What VALORANT matches are live right now?"
"What are the upcoming VALORANT matches?"
"Show me recent match results"
"Break down the G2 vs Xi Lai Gaming match map by map"
"What are the current team rankings?"
"What VALORANT events are happening now?"
"Who's playing at Esports World Cup 2026 and what's the prize pool?"

Team-Specific Queries:

"What are G2 Esports' last 5 games?"
"When does Paper Rex play next?"
"Who's on the Sentinels roster?"
"What's the head-to-head record between Sentinels and LOUD?"

Player & Stats Queries:

"What's aspas's most used agent in the last 90 days?"
"Which agent does Demon1 have the best K:D with?"
"Who are the top 10 players in EU over the last 30 days?"
"Which agents are most picked at Esports World Cup 2026?"

News:

"What's the latest VALORANT roster news?"
"Catch me up on recent VLR headlines"

Tools Reference

Tool	Description
`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

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

See LICENSE file for details.

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.

VLR MCP

Documentation