MCP Server (Model Context Protocol)

VLRdevAPI includes a native Model Context Protocol (MCP) server that connects LLM applications, coding agents, and chat interfaces directly to live Valorant esports data from vlr.gg.

With 40 tools covering matches, series, teams, players, tournaments, editorial news, and high-level composite dossiers, AI models can inspect live schedules, calculate head-to-head records, analyze player agent ratings, and evaluate round-by-round economies without custom scraping code.

InstallationCopy Anchor Link

The MCP server is included as an optional dependency extra:

# Install with MCP dependencies
pip install "vlrdevapi[mcp]"

# Or install with all extras (pandas, polars, openpyxl, pyarrow, mcp)
pip install "vlrdevapi[all]"

Running the ServerCopy Anchor Link

The server communicates over standard input/output (stdio) using the MCP protocol.

Option 1: CLI Entry PointCopy Anchor Link

vlrdevapi-mcp

Option 2: Python ModuleCopy Anchor Link

python -m vlrdevapi.mcp.server

Option 3: Zero-Install via uvxCopy Anchor Link

uvx --from "vlrdevapi[mcp]" vlrdevapi-mcp

Client ConfigurationCopy Anchor Link

Claude DesktopCopy Anchor Link

Add vlrdevapi to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "vlrdevapi": {
      "command": "uvx",
      "args": ["--from", "vlrdevapi[mcp]", "vlrdevapi-mcp"]
    }
  }
}

Or if installed in a local Python virtual environment:

{
  "mcpServers": {
    "vlrdevapi": {
      "command": "/path/to/venv/bin/vlrdevapi-mcp"
    }
  }
}

Cursor IDECopy Anchor Link

In Cursor Settings → Features → MCP Servers, add a new server or configure .cursor/mcp.json:

{
  "mcpServers": {
    "vlrdevapi": {
      "command": "vlrdevapi-mcp"
    }
  }
}

Zed EditorCopy Anchor Link

In Zed's settings.json:

{
  "context_servers": {
    "vlrdevapi": {
      "command": "vlrdevapi-mcp"
    }
  }
}

High-Level Composite ToolsCopy Anchor Link

In addition to granular endpoints, VLRdevAPI provides 8 high-level composite tools designed specifically for multi-step agent reasoning, returning unified context in a single call:

Complete Tool CatalogCopy Anchor Link

MatchesCopy Anchor Link

• matches_upcoming(page: int = 1, max_page: int = 0, return_all: bool = false): Fetch upcoming scheduled matches with team names, event details, and match times.
• matches_live(): Fetch currently live matches with real-time scores, team names, and event info.
• matches_completed(page: int = 1, max_page: int = 0, return_all: bool = false): Fetch past completed match results with final scores, winners, and dates.

Series & GamesCopy Anchor Link

• series_info(series_id: int): Detailed match overview including teams, date, format, score, event, and map vetoes.
• series_players(series_id: int, game_id: str = "all"): Player statistics for a series or specific map (ACS, K/D, ADR, KAST).
• series_rounds(series_id: int, game_id: int): Round-by-round results including round winner, win type, and economy for a map.
• series_performance(series_id: int, game_id: str = "all"): Kill matrix and head-to-head duels between players.
• series_economy(series_id: int, game_id: str = "all"): Team economy data, bank reserves, loadout values, and buy types per round.
• series_replay(series_id: int, game_id: int): 2D spatial replay events, minimap coordinates, kill locations, and loadouts.
• series_vods(series_id: int): VOD links, broadcast streams, and timestamped match recordings.
• series_map_summary(series_id: int, game_id: str): Map-level summary combining economy, replay timeline, and player stats.

TeamsCopy Anchor Link

• team_info(team_id: int): Team profile details including name, tag, country, ranking, and social links.
• team_roster(team_id: int): Active team roster with player names, real names, and staff roles.
• team_stats(team_id: int, last_days: int | None = None, agent_composition: str = "none"): Map win rates, side win percentages (Attack/Defense), and agent compositions.
• team_completed_matches(team_id: int, limit: int = 50, return_all: bool = false): Historical match results for a team.
• team_upcoming_matches(team_id: int): Upcoming scheduled fixtures for a team.
• team_transactions(team_id: int): Roster transactions, player additions, departures, and role transfers.
• team_placements(team_id: int): Tournament results, placement finishes, and prize earnings.

PlayersCopy Anchor Link

• player_info(player_id: int): Player profile including IGN, real name, country, and total tournament winnings.
• player_teams(player_id: int): Career team history, past organizations, and join/leave dates.
• player_agents(player_id: int, timespan: str = "all"): Agent statistics (ACS, K/D, ADR, KAST, pick rates) over a timespan (30d, 60d, 90d, all).
• player_matches(player_id: int, limit: int = 50): Match history for a player with individual ratings and scores.
• player_profile(player_id: int): Consolidated profile combining bio, current team, and top agents.
• player_placements(player_id: int): Tournament placements and prize earnings won by a player.

Events & TournamentsCopy Anchor Link

• events_list(page: int = 1, tier: str = "all", region: str = "all", status: str | None = None): Browse tournaments by tier (vct, vcl, gc, t3), region (americas, emea, pacific, china), and status (ongoing, upcoming, completed).
• event_info(event_id: int): Tournament overview including prize pool, dates, location, and format.
• event_stages(event_id: int): Tournament stages and brackets (Group Stage, Playoffs, Lower Final).
• event_teams(event_id: int): Participating teams and qualified rosters in an event.
• event_matches(event_id: int, stage: str | None = None, state: str = "all"): Scheduled and completed fixtures within a tournament.
• event_standings(event_id: int, stage: str | None = None): Final tournament placements, rank orders, and prize payouts.

Editorial NewsCopy Anchor Link

• news_list(page: int = 1): Latest news articles and headlines from the vlr.gg editorial desk.
• news_article(article_id: int): Full article content with title, author, publish date, and GitHub-flavored Markdown text.

Response Serialization & ArchitectureCopy Anchor Link

All tool responses are serialized using VLRdevAPI's optimized ExportableModel.to_dict() and ExportableModel.to_json() methods. This delivers:

1. Lightweight JSON Payloads: Direct serialization avoids bloated intermediate representations, minimizing token usage in LLM context windows.
2. Graceful Error Trapping: Domain exceptions (such as NotFoundError or ValidationError) are caught and returned as structured JSON error responses rather than crashing the MCP connection:

   Copy Text

   {
     "error": "NotFound",
     "message": "Player with ID 99999999 not found"
   }

3. Strict Validation: All input arguments conform to standard JSON Schemas generated from Pydantic types, ensuring reliable tool calling across Claude, GPT-4, and Gemini.