Skip to content

Python SDK & MCP for VLR.gg

v3.1.0 released

Valorant esportsdata, straightinto Python.

VLRdevAPI reads VLR.gg and returns Pydantic models for matches, players, teams, events, and series. No API key, no account, and no parser to maintain.

Read the docs
uv add vlrdevapi

Used by partnered, Tier 1, Tier 2, and Game Changers orgs.

player.py
import vlrdevapi
player = vlrdevapi.player(11225)
info = player.info()
agents = player.agents(timespan="60d")
print(info.name, info.country)
print(agents.agents[0].agent)
returns Player InfoPlayers reference
player.info()player.teams()player.agents()player.matches()player.profile()
All namespaces

What it handles

The parts you would
otherwise have to write.

No HTML parsing. No selectors that break when VLR.gg ships a redesign. No glue code between the site and your app — just import the client and query the data.

Typed models

No more dict.get("name")

Every response is a Pydantic model with real fields, types, and descriptions. Autocomplete works. Validation is free.

models.pyruntime validation

class PlayerInfo(BaseModel):

player_id: int
name: str
real_name: str
country: str
total_winnings: int

# 13 fields · 0 validation errors

Curried access

Bind once, query anywhere

Pass an ID one time. Every related method hangs off the object you get back.

player.pyid bound once

player = client.player(11225)

player.info()Ethan
player.teams()NRG
player.agents()Kayo · 45%
player.matches()PlayerMatches
player.profile()PlayerProfile
resolving0 / 5 methods

Rate limiting

A good citizen by default

Three requests per second out of the box, with retries and exponential backoff.

1 second window0 / 3 sent
0.00idle
0.33idle
0.67idle
1.0next
window open3 req / sec

Concurrency

Parallel where it counts

Multi-stage endpoints fetch their pages in parallel with a thread pool.

event.stages()thread pool
stage 1
stage 2
stage 3
dispatched togetherjoined once

Timezones

Timezones, handled

VLR.gg renders times for a viewer. Set source_tz once and dates come back UTC-aware.

SeriesInfo.datetimeAmerica/New_York

VLR.gg

07:00 EDT

model

11:00 UTC

source_tz → UTCtz-aware
Model Context Protocol · v3.1.0

Connect any AI assistant
to live Valorant esports.

No API keys. No hosting. No custom glue code. Run with uvx in ten seconds with drop-in support for any MCP-compatible client.

Drop-in ready:Claude DesktopCursorClaude CodeWindsurfOpenCodeDeepSeekCodexGrokZed

Quickest Setup

One terminal command or drop-in JSON

Claude Code CLI
claude mcp add vlrdevapi -- uvx --from "vlrdevapi[mcp]" vlrdevapi-mcp
Cursor / Claude Desktop / Windsurf config
{
  "mcpServers": {
    "vlrdevapi": {
      "command": "uvx",
      "args": ["--from", "vlrdevapi[mcp]", "vlrdevapi-mcp"]
    }
  }
}
Runs isolated via uvxNo venv activation required

What Agents Can Query

40 tools & composite dossiers

“Who is playing live right now in VCT?”

matches_live()

Live scoreboard & active maps

“Compare Sentinels vs FNATIC head-to-head”

compare_teams(team1, team2)

Rosters, form, rankings & earnings

“Give me Derke's career summary and top agents”

get_player_career_summary(id)

ACS, K/D, rating & tournament placements

“What was the round-by-round economy in the Grand Final?”

series_economy(series_id)

Buy matrices, loadouts, credits & bank

Autonomous agents promptView agent prompt

The namespaces

Every surface.
One import.

Bind an ID once, then query everything attached to it. Scroll through the full surface, or jump straight to a namespace.

Browse the full reference
01

Players

Profiles, career teams, agent stats, placements, and match history.

Player Profile
player.py
from vlrdevapi import VLRClient
with VLRClient() as client:
player = client.player(11225)
info = player.info()
teams = player.teams()
agents = player.agents(timespan="90d")
print(info.name, info.country)
print(teams.current_teams[0].name)
print(agents.agents[0].agent)
info()teams()agents()matches()placements()profile()

Player profile

Ethan

Ethan Arnold · United States

Player Info

Top agent · 90d

Kayo · 299 rounds

Rating

1.11

ACS

199.4

K / D

1.05

Kayo45%
Phoenix19%
Omen16%
Career winnings$645,700

Live VLR.gg snapshot · 2026-10-23

02

Teams

Rosters, staff, placements, prize money, and full match history.

Team Placements
team.py
from vlrdevapi import VLRClient
with VLRClient() as client:
team = client.team(1034)
print(team.info().name)
for member in team.roster().players:
print(member.ign, member.roles)
for placement in team.placements().placements[:3]:
print(placement.event_name)
print(placement.placements[0].placement)
info()roster()placements()transactions()stats()completed_matches()

Team profile

NRG

United States · 5 players · 3 staff

Team Roster
01Ethan
Captain
02keiko
Player
03brawk
Player
04mada
Player
05skuba
Player

Winnings

$2,050,375

Best result

Champions 2025 · 1st

Live VLR.gg snapshot · 2026-10-23

03

Series

Scores, map vetoes, round data, player stats, economy, and VODs.

Economy Data
series.py
from vlrdevapi import VLRClient
with VLRClient() as client:
series = client.series(542272)
info = series.info()
rounds = series.rounds(game_id=1)
economy = series.economy(game_id=1)
print(f"{info.team1.name} {info.score1}-{info.score2}")
print(len(rounds.rounds), "rounds")
print(economy.rounds[0].winner.name)
info()rounds()players()performance()economy()vods()

Series overview

NRG vs FNATIC

Valorant Champions 2025 · Grand Final

Series Info
NRG3
FNATIC2
Corrode13–3NRG
Lotus13–6FNC
Abyss13–15NRG
Ascent8–13FNC
Sunset13–5Decider
5 maps102 rounds6 VODs

Live VLR.gg snapshot · 2026-10-23

04

Events

Event metadata, stages, brackets, matches, and final standings.

Event Standings
event.py
from vlrdevapi import VLRClient
with VLRClient() as client:
event = client.event(2863)
print(event.info().name)
for stage in event.stages():
print(stage.name)
standings = event.standings()
for row in standings.stages[0].standings[:3]:
print(row.place, row.team.name)
info()stages()matches()teams()standings()

Event overview

VCT 2026: EMEA Stage 1

Germany · Apr 1 – May 17

Event Standings
PlayoffsMay 7 – May 17
Group StageApr 1 – May 1

Playoffs standings

1stTeam Heretics9 pts
2ndTeam Vitality6 pts
3rdFUT Esports7 pts

Live VLR.gg snapshot · 2026-10-23

05

News

The latest headlines and full articles, converted to clean Markdown.

News Article
news.py
from vlrdevapi import VLRClient
with VLRClient() as client:
page = client.news(page=1)
for article in page.news[:3]:
print(article.title)
full = client.news.article(page.news[0].id)
print(full.author, full.date)
print(full.content_md[:500])
news()news.article()

News article

Evil Geniuses to cease operations

By jenopelle · Oct 23

News Article

The villains bow out after a five-year run in Valorant.

content_md

Evil Geniuses has announced that it will cease competitive and day-to-day operations, effective November 2. The date coincides with the official end of VCT's 2026 contracts and the start of free agency ahead of the 2027 season. The statement from CEO Chris DeAppolonio shared the efforts taken by the org to continue operations, such as stabilizing operations,

United States18 links · Markdown preserved

Live VLR.gg snapshot · 2026-10-23

06

MCP Server

Model Context Protocol server with 41 AI agent tools for Claude Desktop, Cursor, and Zed.

MCPServer
mcp_server.py
# Run via CLI for Claude Desktop or Cursor
# $ vlrdevapi-mcp
# Or initialize in Python:
from vlrdevapi.mcp.server import create_server
server = create_server()
print(f"Server {server.name} initialized with 41 tools")
# Tools: get_match_full_context, get_team_overview,
# compare_teams, series_replay, series_economy...
matches_*series_*team_*player_*event_*composite_*

AI Agent Integration

Model Context Protocol Server

41 Tools · stdio transport · Claude / Cursor ready

MCPServer
get_match_full_contextOverview + stats + VODs
get_team_overviewRoster + form + schedule
series_map_summaryEconomy + replay + stats
CLI commandvlrdevapi-mcp

Live VLR.gg snapshot · 2026-10-23

FAQ

Questions,
answered.

Keys, MCP server, AI integrations, data science exports, coverage, rate limits, and licensing.

Read the full FAQ
Is VLRdevAPI an official VLR.gg API?
No. VLRdevAPI is an independent, open-source Python client and MCP server that reads publicly available pages on VLR.gg and converts them into typed models. It is not affiliated with, endorsed by, or supported by VLR.gg or Riot Games.
Can I connect VLRdevAPI to Claude Desktop, Cursor, or AI coding agents?
Yes! VLRdevAPI includes a native Model Context Protocol (MCP) server. Run "claude mcp add vlrdevapi -- uvx --from \"vlrdevapi[mcp]\" vlrdevapi-mcp" or drop the JSON config into Cursor, Windsurf, Claude Desktop, or custom agent runners. Your assistant gains 40 tools covering match schedules, live scores, player stats, and round-by-round replay timelines without writing any scraping code.
Do I need to host an MCP server or manage background processes?
No. The MCP server runs on demand over standard stdio using uvx. There are no servers to host, no ports to open, and no API keys required. Your AI client launches the process automatically when a session starts and shuts it down when you finish.
Do I need an API key or account?
No. Install the package or run the MCP server and start making calls immediately. There is no key, no signup, no billing, and no environment variable to configure.
Can I export data into Pandas, Polars, or Excel spreadsheets?
Yes! Every model in v3.1 inherits from ExportableModel, giving you one-line export methods: .to_df() for pandas, .to_polars() for Polars, .to_csv(), .to_parquet(), .to_excel(), .to_json(), and .to_markdown().
Does it support async Python?
The Python client is intentionally synchronous to keep the dependency surface minimal and the call path predictable. In an async app, run calls in a worker thread (asyncio.to_thread) or background task. Scripts, scheduled jobs, and data pipelines can use it directly.
How are rate limits handled?
Each client is rate limited to three requests per second by default, configurable with requests_per_second. Requests retry automatically with exponential backoff, so temporary network hiccups do not fail your script.
What data can I actually fetch?
Matches (upcoming, live, completed), series (map scores, player stats, economy buy matrices, 2D kill-feed replays, VODs), teams (rosters, staff, match history, placements, transactions), players (career profiles, agent stats, placements), events (stages, brackets, standings), and editorial news with full Markdown.
Which Python versions are supported?
Python 3.11 and newer, including 3.12, 3.13, 3.14, and 3.15. The package is MIT licensed, so you can use it in commercial and open-source projects without restriction.

Get started

Install the SDK and query the data.

One package, six namespaces, no key. Start with the quickstart, then dig into the endpoint reference.

uv add vlrdevapi

MIT · Python 3.11+ · v3.1.0 · no API key