rivals-api

Marvel Rivals stats from three public sources, through one Python client.

rivals-api brings together RivalsData, RivalsTracker, and Tracker.gg. Look up players, explore matches and heroes, calculate win rates, or use the read-only MCP server in an AI client. It is unofficial and requires Python 3.10+.

RivalsData ────┐
RivalsTracker ─┼──► rivals-api ──► Python client / MCP tools / player dashboard
Tracker.gg ────┘

Get started

python -m pip install rivals-api

from rivals_api import RivalsClient

with RivalsClient() as client:
    player = client.get_player("GS-")  # A player name or numeric UID
    rate = player.stats.win_rate()

    print(player.name, player.level)
    print(rate.wins, rate.games, rate.win_rate_pct)
    print(rate.metadata.coverage)

The default win rate is for the current season, combining Competitive and Quickplay. If the current season cannot be verified, pass a season ID or season="all". The latter means all available tracked history, which may be less than a player's lifetime history.

What makes it useful

Feature	Why it matters
Three providers, one view	Available data from RivalsData, RivalsTracker, and Tracker.gg can fill gaps when a source has less detail or fails. Match results retain source decisions in provider_metadata; win-rate results expose selections and provider errors in metadata.
Win rates with evidence	Normal calculations use win/loss counts rather than averaging provider percentages. Coverage and missing modes are reported, so an incomplete answer is recognizable.
Match-verified rates	method="precise" walks available match history and checks completed outcomes. Hero and class rates assign each match to the longest-played hero when the match details support it. Ambiguous matches stay unresolved.
Persistent match cache	Precise calculations retain history and details in SQLite. Later runs refresh recent pages and reuse verified older matches.
Readable match data	Maps, heroes, ranks, modes, platforms, and seasons have names alongside their original IDs. Models also preserve the source payload in .raw.
AI-ready access	Read-only MCP tools cover player profiles, matches, leaderboards, heroes, and more. show_player_dashboard can display a player card with a live match, hero form, or recent matches.

Pick the stats you need

from rivals_api import RivalsClient

with RivalsClient() as client:
    player = client.get_player("GS-")

    ranked = player.stats.win_rate(mode="competitive")
    quickplay = player.stats.win_rate(mode="quickplay")
    heroes = player.stats.hero_win_rates(season="all")
    classes = player.stats.class_win_rates()

    print(ranked.win_rate_pct, quickplay.win_rate_pct)
    print(heroes.metadata.coverage)

mode accepts "competitive", "quickplay", or "all" (the default). season accepts a provider season ID, "current", or "all". Hero and class results have their own coverage metadata.

Go deeper with match-verified rates

from rivals_api import RivalsClient

with RivalsClient() as client:
    player = client.get_player("GS-")
    rate = player.stats.win_rate(method="precise")
    hero_rates = player.stats.hero_win_rates(method="precise")

    print(rate.win_rate_pct, rate.metadata.coverage)
    print(hero_rates.metadata.unresolved)

The first precise run may fetch many history pages and match details. It checks each provider's complete match record independently; it does not splice hero playtime from different sources. Missing playtime, ties, conflicting outcomes, and other uncertain records are reported as unresolved. See the advanced usage guide for attribution and cache details.

Explore players and matches

from rivals_api import RivalsClient

with RivalsClient() as client:
    candidates = client.search_players("silo")
    for candidate in candidates:
        print(candidate.name, candidate.uid)

    if candidates:
        player = client.get_player(candidates[0].uid)
        history = player.matches.fetch(limit=20)
        if history.matches:
            match = history.matches[0].get_details()
            print(match.map, match.game_mode, match.platform)
            print(match.provider_metadata.errors)

    leaderboard = client.leaderboards.fetch(limit=100)
    tier_list = client.heroes.tier_list()

Match history combines and deduplicates provider results. Details are fetched when you ask for them. More resources include live games, teammates, team-ups, hero metrics, proficiency, factions, and public insights. Browse the API inventory for the full list and observed response shapes.

Use it with an MCP client

python -m pip install "rivals-api[mcp]"

For a local Claude Desktop connection, add this to its configuration and point command at the Python executable where you installed the package:

{
  "mcpServers": {
    "rivals-api": {
      "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
      "args": ["-m", "rivals_api.mcp_server"]
    }
  }
}

On macOS/Linux, use the environment's bin/python path. For local HTTP testing, run uvicorn rivals_api.mcp_server:app --host 127.0.0.1 --port 8000; the endpoint is /mcp. The advanced usage guide covers remote hosting and the player dashboard.

More detail

• Advanced usage and MCP setup
• Provider selection and match details
• Readable game references
• Release notes and migration
• Contributing

RivalsDataClient and the rivalsdata import path remain available for older projects. This project is not affiliated with RivalsData, RivalsTracker, Tracker.gg, NetEase, or Marvel. Public data can be incomplete, private, or stale.