MCSR Tracker

A local tracker for Minecraft Speedrunning with a web dashboard that runs entirely on your computer.

Note: This tracker is built for Any% Glitchless, and will probably not work with other categories.

I built this tracker because I wanted a simple, fully local and offline tracker. It is not meant to replace PaceMan Tracker but to offer a local alternative for those who prefer it.

Features

• Fully local, no account or login required
• Automatic run tracking
• Web dashboard for viewing run statistics
• Run history and split data
• Save seed when /seed is run

Tracking Behavior

• World tracking: Worlds not created by Atum won't be tracked.
• Seed: The world seed is only saved when /seed is run. If /seed has not been run, the seed cannot be saved because the level data is encrypted.
• Cheat detection: Any splits recorded after cheats are enabled won't be saved.
• Structure splits: Bastion and fortress splits are normalized into Structure 1 / Structure 2 based on which structure is entered first.
• Run data: Runs are recorded automatically while the tracker is running.

Installation

Requirements

• Python 3.14+
• Required Mods:
  • Atum
  • SpeedrunIGT
  • Hermes
  • Hermes Core

Please refer to the Minecraft Speedrunning public resources to download the required mods.

Automatic Installation

You can inspect the install script before running it.

Linux

Default installation path: $XDG_DATA_HOME/mcsr-tracker (defaults to ~/.local/share/mcsr-tracker)

curl -fsSL https://raw.githubusercontent.com/chengggit/MCSR-Tracker/main/install.py | python

Windows

Default installation path: %LOCALAPPDATA%\mcsr-tracker

irm https://raw.githubusercontent.com/chengggit/MCSR-Tracker/main/install.py | py

Follow the on-screen instructions after installation to make mcsr a global command.

Manual Installation

1. Download mcsr_tracker-<version>-py3-none-any.whl from the latest release.
2. Follow the commands below to create a Python virtual environment and install the tracker.

Linux

python -m venv venv
source venv/bin/activate
pip install path/to/mcsr_tracker-<version>-py3-none-any.whl

After installation, run:

mcsr setup

Windows

python -m venv venv
venv\Scripts\activate
pip install C:\path\to\mcsr_tracker-<version>-py3-none-any.whl

After installation, run:

mcsr setup

From Source

With pip:

git clone https://github.com/chengggit/MCSR-Tracker.git
cd MCSR-Tracker
python -m venv venv

# Linux
source venv/bin/activate

# Windows
venv\Scripts\activate

pip install .

After installation, run:

mcsr setup

With uv:

git clone https://github.com/chengggit/MCSR-Tracker.git
cd MCSR-Tracker
uv sync --no-dev

After installation, run:

mcsr setup

Usage

Start the tracker:

mcsr track <instance-name>

Start the tracker and open the web dashboard:

mcsr track <instance-name> --dashboard

Start the web dashboard:

mcsr dashboard

More commands and options can be found with:

mcsr --help

Development

Prerequisites

• Python 3.14+
• uv
• Node.js

Clone the repository and install dependencies:

git clone https://github.com/chengggit/MCSR-Tracker.git
cd MCSR-Tracker
uv sync
npm install

Development Commands

uv run poe dev            # Start the development server with hot reload
uv run poe lint           # Lint the project
uv run poe fix            # Lint and automatically fix issues
uv run poe format         # Format the project
uv run poe format-check   # Check formatting
uv run poe typecheck      # Run type checking

API

The API is available at: http://127.0.0.1:8000/api

Interactive API documentation with Swagger UI: http://127.0.0.1:8000/docs

Alternative API documentation with ReDoc: http://127.0.0.1:8000/redoc

License

This project is licensed under the MIT License.

Contribution

All contributions are welcome!