REST APIKein API-SchlüsselCORSJSON · PNG · HTML

MCAPI.TR Entwicklerplattform

API-Dokumentation

Der vollständige MCAPI.TR-Entwicklerleitfaden für Minecraft-Java-, Legacy- und Bedrock-Server sowie Icons, Banner, Widgets, Trends und Plattformstatistiken.

OpenAPI JSON Live testen

Basis-URLhttps://mcapi.tr/api/v1

01 — Schnellstart

Die erste Antwort in Sekunden

Keine Einrichtung und keine Schlüssel. Client wählen, Beispiel kopieren und ausführen.

curl

curl "https://mcapi.tr/api/v1/status/mc.hypixel.net"

02 — API-Testbereich

Live-Anfrage im Browser senden

Die Anfrage geht direkt an die MCAPI.TR-API; die formatierte Antwort erscheint unten.

03 — Endpunktreferenz

Alle öffentlichen Endpunkte

Eine Karte öffnen, um Parameter, Cache-Verhalten und ausführbare Beispiele zu sehen.

GET/api/v1/status

API-Statusprüfung

Prüft Verfügbarkeit, Version und Serverzeit. Ein leichter Endpunkt für Uptime-Monitoring.

application/json

Authentifizierung

Kein API-Schlüssel erforderlich

Cache

Keiner

Content-Type

application/json

Beispielanfrage

bash

curl "https://mcapi.tr/api/v1/status"

Beispielantwort

json

{
  "status": "OK",
  "timestamp": "2026-09-08T20:12:00.000Z",
  "service": "mcapi.tr-engine",
  "version": "0.1.0"
}

GET/api/v1/status/:address

Minecraft-Serverstatus

Liefert den Status von Java-, Legacy-Java- oder Bedrock-Servern samt Spieler-, Versions-, MOTD-, Icon- und Latenzdaten.

application/json

Authentifizierung

Kein API-Schlüssel erforderlich

Cache

Standardmäßig 60 Sekunden

Content-Type

application/json

Parameter

Parameter	Position	Typ	Standard	Beschreibung
`address`*	path	string	—	Hostname oder IP; ein Port kann angehängt werden: play.example.net:25565
`legacy`	query	boolean	false	Erzwingt das Java-Ping-Protokoll vor 1.7.2.
`bedrock`	query	boolean	false	Verwendet die Bedrock-Edition-Abfrage; Standardport ist 19132.

Beispielanfrage

bash

curl "https://mcapi.tr/api/v1/status/mc.hypixel.net"
curl "https://mcapi.tr/api/v1/status/bedrock.example.net:19132?bedrock=true"

Beispielantwort

json

{
  "query": {
    "host": "mc.hypixel.net",
    "port": 25565,
    "legacy": false,
    "bedrock": false
  },
  "server_id": "f17d4f75-...",
  "ip_address": "209.222.115.11",
  "icmp": true,
  "online": true,
  "stale": false,
  "error": null,
  "checked_at": "2026-09-12T15:59:36.430Z",
  "version": { "name": "Requires MC 1.8 / 1.21", "protocol": 47 },
  "players": { "online": 52184, "max": 200000, "sample": [] },
  "motd": {
    "raw": "§aHypixel Network",
    "clean": "Hypixel Network",
    "html": "<span style=\"color:#55FF55\">Hypixel Network</span>",
    "raw_lines": ["§aHypixel Network"],
    "clean_lines": ["Hypixel Network"]
  },
  "favicon": "data:image/png;base64,...",
  "srvRecord": null,
  "roundTripLatency": 18
}

GET/api/v1/trends

Trendserver

Liefert nach Trendwert sortierte Server mit Cursor-basierter Seitennavigation.

application/json

Authentifizierung

Kein API-Schlüssel erforderlich

Cache

5 min

Content-Type

application/json

Parameter

Parameter	Position	Typ	Standard	Beschreibung
`limit`	query	integer	10	Seitengröße, begrenzt auf 1 bis 50.
`cursor`	query	UUID	—	Der Wert meta.nextCursor aus der vorherigen Antwort.

Beispielanfrage

bash

curl "https://mcapi.tr/api/v1/trends?limit=10"

Beispielantwort

json

{
  "success": true,
  "data": [
    {
      "server_id": "f17d4f75-...",
      "hostname": "mc.hypixel.net",
      "address": "mc.hypixel.net",
      "port": 25565,
      "edition": "java",
      "trend_score": 842,
      "daily_growth": 14.6,
      "is_online": true,
      "stale": false,
      "checked_at": "2026-09-12T15:59:36.430Z",
      "players_online": 52184,
      "players_max": 200000,
      "version": "Requires MC 1.8 / 1.21",
      "favicon": "21aa8597...",
      "record_players": 74312,
      "uptime_percentage": 99.8
    }
  ],
  "meta": { "nextCursor": "f17d4f75-...", "hasNext": true, "limit": 10 }
}

GET/api/v1/stats

Globale Plattformstatistiken

Liefert Summen zu Anfragen, geprüften Servern, Online-Rate, aktiven Spielern und letzten Prüfungen.

application/json

Authentifizierung

Kein API-Schlüssel erforderlich

Cache

60 sec

Content-Type

application/json

Beispielanfrage

bash

curl "https://mcapi.tr/api/v1/stats"

Beispielantwort

json

{
  "totalRequests": 1284502,
  "apiRequests": 612340,
  "serverQueries": 672162,
  "totalChecks": 672162,
  "onlineServers": 428,
  "offlineServers": 91,
  "activePlayers": 184205,
  "recentChecks": [],
  "onlineRate": 82.5
}

GET/api/v1/icon/dynamic

Server-Icon

Liefert das Server-Favicon oder ersatzweise das MCAPI.TR-Standardbild.

image/png | image/webp

Authentifizierung

Kein API-Schlüssel erforderlich

Cache

Browser 1 Tag, CDN 7 Tage

Content-Type

image/png | image/webp

Parameter

Parameter	Position	Typ	Standard	Beschreibung
`address`*	query	string	—	Serveradresse. server wird als rückwärtskompatibler Alias akzeptiert.
`size`	query	integer	80	WebP-Ausgabegröße zwischen 16 und 256 Pixeln.
`format`	query	png \| webp	png	Erzeugt bei webp ein optimiertes quadratisches Bild.

Beispielanfrage

bash

curl "https://mcapi.tr/api/v1/icon/dynamic?address=mc.hypixel.net&size=128&format=webp" --output server.webp

GET/api/v1/icon/sharp

Abgerundetes Server-Icon

Erzeugt ein skaliertes PNG-Server-Icon mit abgerundeten Ecken.

image/png

Authentifizierung

Kein API-Schlüssel erforderlich

Cache

Browser 1 Tag, CDN 7 Tage

Content-Type

image/png

Parameter

Parameter	Position	Typ	Standard	Beschreibung
`address`*	query	string	—	Server-Hostname oder IP-Adresse.
`size`	query	integer	128	Ausgabegröße zwischen 32 und 512 Pixeln.

Beispielanfrage

bash

curl "https://mcapi.tr/api/v1/icon/sharp?address=mc.hypixel.net&size=256" --output icon.png

GET/api/v1/banner/:address

Serverstatus-Banner

Erzeugt ein teilbares PNG-Banner mit Servername, Spielern, MOTD, Ping und Favicon.

image/png

Authentifizierung

Kein API-Schlüssel erforderlich

Cache

Abhängig von Server-/CDN-Richtlinie

Content-Type

image/png

Parameter

Parameter	Position	Typ	Standard	Beschreibung
`address`*	path	string	—	Server, für den das Banner erzeugt wird.
`size`	query	small \| normal \| large	normal	Ausgabegröße: 400×130, 600×180 oder 800×240.
`style`	query	modern \| classic	modern	Darstellung des Banners.
`textColor`	query	hex color	#FFFFFF	Primäre Textfarbe.
`accentColor`	query	hex color	#10B981	Akzentfarbe der Spielerzahl.
`showFavicon / showMotd / showPing`	query	boolean	true	Schaltet Icon, MOTD und Latenz einzeln ein oder aus.
`borderRadius`	query	number	0.5	Multiplikator für den Eckenradius.

Beispielanfrage

bash

curl "https://mcapi.tr/api/v1/banner/mc.hypixel.net?size=large&accentColor=%2310B981" --output banner.png

GET/api/v1/banner/motd

MOTD-Textbanner

Wandelt Minecraft-formatierten MOTD-Text ohne Serverabfrage in ein 800×180-PNG um.

image/png

Authentifizierung

Kein API-Schlüssel erforderlich

Cache

Kein Anwendungscache

Content-Type

image/png

Parameter

Parameter	Position	Typ	Standard	Beschreibung
`motd`*	query	string	—	MOTD-Text mit bis zu 300 Zeichen.
`textColor`	query	hex color	#FFFFFF	Standardtextfarbe.
`accentColor`	query	hex color	#10B981	Akzentfarbe des Hintergrunds.

Beispielanfrage

bash

curl "https://mcapi.tr/api/v1/banner/motd?motd=%C2%A7aWelcome" --output motd.png

GET/api/v1/widget/:size/:address

Einbettbares HTML-Widget

Liefert anpassbares Live-Serverstatus-HTML für Websites und Dashboards.

text/html

Authentifizierung

Kein API-Schlüssel erforderlich

Cache

60 sec + stale-while-revalidate

Content-Type

text/html

Parameter

Parameter	Position	Typ	Standard	Beschreibung
`size`*	path	small \| normal \| large	—	Widget-Layout und Standardhöhe.
`address`*	path	string	—	Serveradresse; demo kann für die Vorschau genutzt werden.
`theme`	query	dark \| light	dark	Grundlegendes Farbschema.
`showPlayers / showVersion / showMotd`	query	boolean	true	Schaltet die wichtigsten Informationsfelder einzeln um.
`showLatency / showFavicon`	query	boolean	true	Steuert Ping- und Favicon-Sichtbarkeit.
`showProtocol / showBorder`	query	boolean	false	Zeigt optional Protokoll und Rahmen.
`bgColor / textColor`	query	hex color	—	Hintergrund- und Textfarben des Widgets.
`onlineColor / offlineColor`	query	hex color	#10b981 / #ef4444	Farben für Online- und Offline-Status.
`gradientBg / gradientFrom / gradientTo`	query	boolean / hex	false	Steuerung des Verlaufshintergrunds.
`statusIndicator`	query	dot \| text \| badge \| none	dot	Darstellung der Statusanzeige.
`iconSize`	query	small \| medium \| large	medium	Favicon-Größe.
`font`	query	Inter \| Roboto \| Poppins \| Montserrat \| Outfit	—	Google-Fonts-Schriftart.
`textAlign`	query	left \| center \| right	left	Textausrichtung.
`customHeight`	query	CSS px	—	Benutzerdefinierte Höhe von 50 bis 600 Pixeln.
`borderRadius / borderWidth`	query	number	0.75 / 1	Maße für Ecken und Rahmen.
`hoverEffect / glowEffect / boxShadow`	query	boolean	false	Aktiviert visuelle Effekte.
`playerBarStyle`	query	default \| gradient \| striped \| animated	default	Darstellung der Spielerauslastung.

Beispielanfrage

bash

curl "https://mcapi.tr/api/v1/widget/normal/mc.hypixel.net?theme=dark&showFavicon=true"

04 — Schema

Felder der Serverantwort

Feld	Typ	Beschreibung
`query`	object	Aufgelöster Host, Port und Abfragemodus.
`server_id`	UUID	Stabile Serverkennung innerhalb von MCAPI.TR.
`online`	boolean	Ob der Minecraft-Ping erfolgreich war.
`stale`	boolean	Ob die Antwort aus der letzten erfolgreichen Abfrage statt aus einem aktuellen Ping stammt.
`checked_at`	ISO 8601	UTC-Zeitpunkt der in dieser Antwort dargestellten Serverprüfung.
`icmp`	boolean	ICMP-Erreichbarkeit der Ziel-IP.
`version`	object \| null	Versionsbezeichnung und Protokollnummer des Servers.
`players`	object \| null	Onlinezahl, Kapazität und optionale Spielerbeispiele.
`motd`	object \| null	Rohe, bereinigte und HTML-MOTD-Formen samt Zeilenlisten.
`favicon`	data URL \| null	Base64-kodiertes Server-Favicon.
`srvRecord`	object \| null	Details des aufgelösten Minecraft-SRV-Eintrags, falls die Erkennung verwendet wurde.
`roundTripLatency`	number \| null	Minecraft-Abfragelatenz in Millisekunden.
`error`	string \| null	Sichere Fehlerzusammenfassung einer fehlgeschlagenen Abfrage.

HTTP

Statuscodes

200Anfrage erfolgreich.

400Ungültige Adresse oder Abfrageparameter.

404Server ist offline oder nicht erreichbar.

429Anfragelimit pro Minute überschritten.

500Unerwarteter Serverfehler.

503Wartungsmodus ist aktiv.

Richtlinien

Limits und Caching

status:120 Anfragen pro Minute und IP.
default:Standardmäßig 300 Anfragen pro Minute für allgemeine Endpunkte.
media:Bis zu 5.000 Anfragen pro Minute für Icon-, Banner- und Widget-Endpunkte.
cors:Öffentliche API-Endpunkte erlauben alle Browser-Origins.
privacy:Die Anfrageprofilierung speichert weder rohe IP-Adressen noch User-Agents.

Offizielle SDKs

API mit Node.js und Python verwenden

Offizielle Clients ohne Abhängigkeiten bieten typisierte Serverabfragen, Erkennung, Statistiken und Medienhelfer ohne API-Schlüssel.

Node.js

mcapitr

npm ↗

Promise-basierter Node.js-Client mit vollständigen TypeScript-Deklarationen und Buffer-Helfern für erzeugte Medien.

bash

npm install mcapitr

Node.js 18+TypeScriptPromise API

Python

mcapitr

PyPI ↗

Synchrone und asynchrone Python-Clients mit typisierten Ausnahmen, Seitennavigation und Byte-Downloads.

bash

pip install mcapitr

Python 3.9+TypedSync + Async

Die erste Antwort in Sekunden

Live-Anfrage im Browser senden

Alle öffentlichen Endpunkte

API-Statusprüfung

Beispielanfrage

Beispielantwort

Minecraft-Serverstatus

Parameter

Beispielanfrage

Beispielantwort

Trendserver

Parameter

Beispielanfrage

Beispielantwort

Globale Plattformstatistiken

Beispielanfrage

Beispielantwort

Server-Icon

Parameter

Beispielanfrage

Abgerundetes Server-Icon

Parameter

Beispielanfrage

Serverstatus-Banner

Parameter

Beispielanfrage

MOTD-Textbanner

Parameter

Beispielanfrage

Einbettbares HTML-Widget

Parameter

Beispielanfrage

Felder der Serverantwort

Statuscodes

Limits und Caching

API mit Node.js und Python verwenden

mcapitr

mcapitr

Datenschutzrichtlinie

Schutz Ihrer persönlichen Daten

Gesammelte Daten

Cookies

Datensicherheit

Kontakt

Nutzungsbedingungen

Servicebedingungen

Service-Definition

Nutzungsbeschränkungen

Haftungsausschluss

Rechte an geistigem Eigentum

Änderungen

Kontakt