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:

General Information:

• get_upcoming_matches - Get upcoming VALORANT matches with team names, events, and timing
• get_match_results - View recent match results with scores and events
• get_team_rankings - Access current team rankings (top 20 by region)
• get_events - Browse ongoing, upcoming, and completed VALORANT tournaments

Team-Specific:

• get_team_matches - Get recent or upcoming matches for a specific team
• search_team - Search for specific teams and get their information

Player-Specific:

• get_player_stats - Get detailed player profile with agent statistics and performance metrics (supports time filtering: 30d, 60d, 90d, all)

Quick Start

Installation

1. Clone this repository:

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

2. 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

3. 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 are the upcoming VALORANT matches?"
• "Show me recent match results"
• "What are the current team rankings?"
• "What VALORANT events are happening now?"

Team-Specific Queries:

• "What are G2 Esports' last 5 games?"
• "When does Paper Rex play next?"
• "Show me Sentinels' recent matches"

Player-Specific Queries:

• "What's aspas's most used agent in the last 90 days?"
• "Show me TenZ's agent statistics for all time"
• "Which agent does Demon1 have the best K:D with?"
• "What are Less's stats in the last 30 days?"
• "Show me Chronicle's performance across all agents"

Tools Reference

Tool	Description
get_upcoming_matches(limit)	Returns upcoming VALORANT matches
get_match_results(limit)	Returns recent match results with scores
get_team_rankings(region)	Returns top 20 ranked teams by region
get_team_matches(team_name, limit, match_type)	Returns team-specific matches (recent/upcoming)
search_team(team_name)	Search for a specific team
get_events(status)	Returns VALORANT tournaments and events
get_player_stats(player_name, timespan)	Returns player profile with detailed agent statistics (timespan: 30d, 60d, 90d, all)

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 7 data scraping tools
• Connection to VLR.gg

Project Structure

src/
  vlr_mcp.py           # Main MCP server (composes tool modules)
  config.py            # Shared configuration (base URL, headers, timeouts)
  tools/
    matches.py         # get_upcoming_matches, get_match_results
    teams.py           # get_team_rankings, search_team, get_team_matches
    players.py         # get_player_stats
    events.py          # get_events
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.