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.

Related MCP server: Marvel Rivals MCP

What makes it useful

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.