MTG Player Info

A simple NPM module and CLI tool to pull Magic: The Gathering player data from various sources (Unity League, MTG Elo Project, Melee, and Topdeck).

Installation

npm i -g mtg-player-info

CLI Usage

mtg-player-info --unity-id 16215 --mtgelo-id 3irvwtmk --melee-user k0shiii --topdeck-handle k0shiii

or without previous installation

npx mtg-player-info --unity-id 16215 --mtgelo-id 3irvwtmk --melee-user k0shiii --topdeck-handle k0shiii

Output Format

The tool returns a JSON object representing the player and their combined metadata. Redundant information like Name, Photo, Country, Age, and Hometown is merged into a general section, while source-specific data is kept in the sources section.

Deduplication and Merging Logic

• Priority: Merging follows a "first-come, first-served" approach based on the order of sources provided in the command line or processed by the manager. For instance, the first name and first valid photo URL found will be used as the primary name and photo for the player.
• Deduplication: If multiple IDs point to the exact same profile URL, the profile is only processed once to avoid redundant data in the sources section.
• General Metadata: Fields like Age, Country, and Hometown are extracted from the first source that provides them and placed in the general section.

Example output:

{
  "name": "Björn Kimminich",
  "photo": "https://unityleague.gg/media/player_profile/1000023225.jpg",
  "general": {
    "Age": "45",
    "Bio": "Smugly held back on an Untimely Malfunction against a Storm player going off, being totally sure that you can redirect the summed-up damage of their Grapeshots back to their face with its \"Change the target of target spell or ability with a single target\" mode.",
    "Team": "Mull to Five",
    "Country": "de",
    "Hometown": "Hamburg",
    "Win Rate": "42.09%"
  },
  "sources": {
    "Unity League": {
      "url": "https://unityleague.gg/player/16215/",
      "data": {
        "Local organizer": "Mulligan TCG Shop",
        "Rank Germany": "58",
        "Rank Europe": "584",
        "Rank Points": "274",
        "Record": "38-38-5",
        "Win Rate": "49.0%"
      }
    },
    "MTG Elo Project": {
      "url": "https://mtgeloproject.net/profile/3irvwtmk",
      "data": {
        "player_id": "3irvwtmk",
        "current_rating": "1466",
        "record": "9-12-1",
        "Win Rate": "40.91%"
      }
    },
    "Melee": {
      "url": "https://melee.gg/Profile/Index/k0shiii",
      "data": {}
    },
    "Topdeck": {
      "url": "https://topdeck.gg/profile/@k0shiii",
      "data": {
        "Tournaments": "2",
        "Record": "4-6-1",
        "Win Rate": "36.36%",
        "Conversion": "0%"
      }
    }
  }
}

Supported Sources

The following sites are currently supported based on HTML scraping and/or API calls. In general, API calls are preferred over scraping due to their higher reliability and independence from site structure changes.

| Site | Method | |-----------------|------------------------------------------------------------------------------| | Unity League | ✅Scraping | | MTG Elo Project | ✅Scraping | | Topdeck | ✅Scraping | | Melee | 🚧Scraping/API (#1) |

Note: Some sites may have anti-bot protections that can lead to "Maximum number of redirects exceeded" or "403 Forbidden" errors depending on the execution environment.

Contribution Guidelines

1. All PRs should have a dedicated scope (e.g. not mixing code refactorings with delivering a new feature) and reasonable size.
2. Noise (e.g. unnecessary comments) generated by AI tools must be removed before opening a PR.
3. All Git commits within a PR must be signed off to indicate the contributor's agreement with the Developer Certificate of Origin.
4. Particularly low-effort contributions (e.g. incomplete typo fixes in a single file, trivial text changes, code formatting) or any forms of potential "contribution farming" must not be submitted as PRs.

Licensing

This program is free software: you can redistribute it and/or modify it under the terms of the MIT license. MTG Player Info and any contributions are Copyright © by Bjoern Kimminich 2026.