mcsr-mcp

<p align="center"> <img src="assets/banner.jpg" alt="MCSR Ranked MCP" width="100%" /> </p>

<p align="center"> <a href="https://github.com/miyakejima/mcsr-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a> <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node.js >= 18" /></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-blueviolet.svg" alt="MCP Compatible" /></a> <a href="https://mcsrranked.com"><img src="https://img.shields.io/badge/data-mcsrranked.com-orange.svg" alt="MCSR Ranked" /></a> </p>

<br />

mcsr-mcp is a Model Context Protocol server that gives AI assistants real-time access to the MCSR Ranked competitive Minecraft speedrunning API.

Ask your AI anything about any ranked player — form analysis, personal bests, ELO history, pre-match scouting, rivals, decay status — in plain language. No commands, no dashboards, no manual API calls.

"Scout v_strid before my match"
"What are Feinberg's top 10 fastest runs this season?"
"Has v_strid been tilting? Show me their ELO history"
"When does my rank decay?"
"Who are v_strid's rivals and where are they weakest?"

---

How it looks

<p align="center"> <img src="assets/example-output.jpg" alt="Example tool output" width="80%" /> </p>

---

What it can do

<p align="center"> <img src="assets/tools-diagram.jpg" alt="Tools overview" width="90%" /> </p>

All 18 tools

Tool	What it does
get_player	Profile, ELO, rank, tier, stats, Twitch/YouTube links
get_player_matches	Raw match history with seed and bastion data
get_player_seasons	Season-by-season performance history
get_versus	Head-to-head record between two players
get_versus_matches	Full H2H match list
get_leaderboard	Global ranked standings
get_match	Single match details by ID
get_weekly_race	Weekly race leaderboard
analyze_player_form	Win rates by seed type, bastion type, opponent ELO bracket
get_rank_context	Leaderboard neighborhood + ELO gaps to milestone ranks
scout_opponent	Pre-match scouting report with Twitch VOD timestamps
compare_players	Side-by-side player comparison with H2H
find_rivals	Opponents a player consistently loses to
get_personal_bests	Fastest ranked completions, filterable by seed type
get_elo_history	Full ELO trajectory — peak, trough, streaks, per-match deltas
get_decay_status	Exact decay date + urgency level (✅ SAFE → 🚨 CRITICAL)
analyze_session_form	Per-session stats grouped by playtime gaps
get_capabilities	Ask your AI "what can this MCP do?" to get the full guide

---

Installation

Requirements

• Node.js v18 or later
• An MCP-compatible AI client (see below)

1. Clone and build

git clone https://github.com/miyakejima/mcsr-mcp.git
cd mcsr-mcp
npm install
npm run build

The compiled server will be at dist/index.js.

2. Add to your AI client

Add the following block to your MCP config file:

{
  "mcpServers": {
    "mcsr": {
      "command": "node",
      "args": ["/absolute/path/to/mcsr-mcp/dist/index.js"]
    }
  }
}

Config file locations

Client	Config file
Antigravity	~/.gemini/config/mcp_config.json
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Cursor	.cursor/mcp.json (project) or ~/.cursor/mcp.json (global)
Windsurf	~/.codeium/windsurf/mcp_config.json

Windows path example:

{
  "mcpServers": {
    "mcsr": {
      "command": "node",
      "args": ["C:/Users/yourname/mcsr-mcp/dist/index.js"]
    }
  }
}

3. Restart your client

After saving, restart your AI client. The mcsr server will appear with all 18 tools enabled. You can verify by asking:

"What can the mcsr MCP do?"

---

Usage examples

Pre-match scouting

"Scout v_strid — I'm miyakejima"

Returns: recent form, seed/bastion win rates, weaknesses, your H2H record, and Twitch VOD links with timestamps so you can jump straight to their runs.

Form analysis

"What are Feinberg's weaknesses over the last 30 matches?"

Returns: win rate by every seed type and bastion variant, ELO bracket performance, streak data.

Personal bests

"Show me v_strid's top 5 fastest Buried Treasure runs"

Returns: ranked list of fastest completions for that seed, with opponent, date, and VOD timestamp link.

ELO history

"Has v_strid been tilting lately? Show me their last 50 matches"

Returns: full ELO timeline, peak/trough, total delta, longest win and loss streaks.

Decay tracker

"When does my rank decay? I'm miyakejima"

Returns: exact date, days/hours remaining, urgency level, last match date.

Rivals

"Who does Feinberg consistently lose to?"

Returns: opponents with a net losing record, sorted by ELO proximity and net loss count.

---

Notes

• No API key required. Uses the public MCSR Ranked REST API at api.mcsrranked.com.
• Rate limit: The API allows ~500 requests per 10 minutes. A 150ms delay between requests is applied automatically.
• Loss times are unavailable. The MCSR Ranked API only records the winner's finish time — this is an upstream API limitation.
• VOD links include Twitch timestamps to jump directly to the run start.
• Season filtering: Add "season 10" (or any number) to any query to pull historical season data.
• Seed type filter on get_personal_bests: RUINED_PORTAL, SHIPWRECK, DESERT_TEMPLE, VILLAGE, BURIED_TREASURE.

---

Data source

All data is from the official MCSR Ranked API. This project is not affiliated with or endorsed by MCSR Ranked.

---

License

MIT