Python SDK & MCP for VLR.gg
v3.1.0 releasedValorant 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.
uv add vlrdevapiUsed by partnered, Tier 1, Tier 2, and Game Changers orgs.
import vlrdevapi | |
| |
player = vlrdevapi.player(11225) | |
| |
info = player.info() | |
agents = player.agents(timespan="60d") | |
| |
print(info.name, info.country) | |
print(agents.agents[0].agent) |
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.
class PlayerInfo(BaseModel):
# 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 = client.player(11225)
Rate limiting
A good citizen by default
Three requests per second out of the box, with retries and exponential backoff.
Concurrency
Parallel where it counts
Multi-stage endpoints fetch their pages in parallel with a thread pool.
Timezones
Timezones, handled
VLR.gg renders times for a viewer. Set source_tz once and dates come back UTC-aware.
VLR.gg
07:00 EDT
model
11:00 UTC
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.
Quickest Setup
One terminal command or drop-in JSON
claude mcp add vlrdevapi -- uvx --from "vlrdevapi[mcp]" vlrdevapi-mcp{
"mcpServers": {
"vlrdevapi": {
"command": "uvx",
"args": ["--from", "vlrdevapi[mcp]", "vlrdevapi-mcp"]
}
}
}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
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 referencePlayers
Profiles, career teams, agent stats, placements, and match history.
info()teams()agents()matches()placements()profile()Player profile
Ethan
Ethan Arnold · United States
Top agent · 90d
Kayo · 299 rounds
Rating
1.11
ACS
199.4
K / D
1.05
Live VLR.gg snapshot · 2026-10-23
Teams
Rosters, staff, placements, prize money, and full match history.
info()roster()placements()transactions()stats()completed_matches()Team profile
NRG
United States · 5 players · 3 staff
Winnings
$2,050,375
Best result
Champions 2025 · 1st
Live VLR.gg snapshot · 2026-10-23
Series
Scores, map vetoes, round data, player stats, economy, and VODs.
info()rounds()players()performance()economy()vods()Series overview
NRG vs FNATIC
Valorant Champions 2025 · Grand Final
Live VLR.gg snapshot · 2026-10-23
Events
Event metadata, stages, brackets, matches, and final standings.
info()stages()matches()teams()standings()Event overview
VCT 2026: EMEA Stage 1
Germany · Apr 1 – May 17
Playoffs standings
Live VLR.gg snapshot · 2026-10-23
News
The latest headlines and full articles, converted to clean Markdown.
news()news.article()News article
Evil Geniuses to cease operations
By jenopelle · Oct 23
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,
Live VLR.gg snapshot · 2026-10-23
MCP Server
Model Context Protocol server with 41 AI agent tools for Claude Desktop, Cursor, and Zed.
matches_*series_*team_*player_*event_*composite_*AI Agent Integration
Model Context Protocol Server
41 Tools · stdio transport · Claude / Cursor ready
vlrdevapi-mcpLive VLR.gg snapshot · 2026-10-23
Guides & reference
Start from a recipe,
stay for the reference.
Tutorials
- Getting started with VLRdevAPIFrom an empty project to a first typed response.
- Building a real-time match monitorPoll live matches, track the score, and fire an alert.
- Building a Valorant esports Discord botSlash commands for fixtures, rosters, and live scores.
- Player analytics with pandasTurn agent and match stats into a DataFrame.
- Event analytics with PolarsBreak a tournament down by placement and prize money.
From the blog
Notes on building
with esports data.
Announcing VLRdevAPI v3.1: MCP Server, Universal Tabular Exports, and Python 3.15 Ready
Production/Stable release introducing a native Model Context Protocol (MCP) server with 41 AI agent tools, universal tabular data exports (pandas, Polars, CSV, Parquet, Excel, JSON, Markdown), and Python 3.15 readiness.
Read post2026-10-23Announcing VLRdevAPI v3.0
Major economy and data release introducing kill-feed series replays, buy-type matrices, per-round economy, head-to-head history, and player tournament placements.
Read post2026-10-15VLRdevAPI vs Other Valorant Esports APIs
How VLRdevAPI compares to self-hosted VLR.gg JSON services, the Riot official API, and writing your own scraper, with the cost and upkeep of each.
Read postFAQ
Questions,
answered.
Keys, MCP server, AI integrations, data science exports, coverage, rate limits, and licensing.
Read the full FAQIs VLRdevAPI an official VLR.gg API?
Can I connect VLRdevAPI to Claude Desktop, Cursor, or AI coding agents?
Do I need to host an MCP server or manage background processes?
Do I need an API key or account?
Can I export data into Pandas, Polars, or Excel spreadsheets?
Does it support async Python?
How are rate limits handled?
What data can I actually fetch?
Which Python versions are supported?
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 vlrdevapiMIT · Python 3.11+ · v3.1.0 · no API key