MCRestAPI

A Fabric mod that exposes a REST API and real-time event stream (SSE) for monitoring and controlling dedicated Minecraft servers. Built on top of the JDK's built-in HTTP server with zero external dependencies. Available for Minecraft 1.21.11 and 26.1+ — download the file that matches your version.

Features

• REST API for server monitoring (TPS, MSPT, memory, CPU, player count, server properties)
• Real-time Server-Sent Events (SSE) stream for chat, joins, leaves, deaths and game messages
• Complete player data: health, food, position, dimension, ping, gamemode, OP status, skin head URL
• World data: seed, time, weather, difficulty, entity count, loaded chunks, per-dimension stats
• Remote command execution via API
• Built-in admin dashboard (single-page web app) for monitoring and management
• Bundled Swagger UI with OpenAPI 3.1.0 specification
• Multi-key authentication with granular permissions
• Master key for administrative operations
• CORS configuration with per-origin allowlist
• API keys hashed with PBKDF2-SHA256 (never stored in plain text)
• Zero external dependencies (uses JDK built-in HTTP server)
• Virtual threads for lightweight concurrency
• Server-side only (does not run on clients)

Requirements

Component 1.21.11 line 26.1 line Minecraft 1.21.11 26.1.x Java >= 21 >= 25 Fabric Loader >= 0.18.4 >= 0.19.3 Fabric API any any

Each release on Modrinth is tagged with its supported Minecraft version — install the one matching your server.

Installation

1. Download the latest mcrestapi-x.x.x.jar from this page or from GitHub Releases
2. Place the JAR file in the mods/ folder of your Fabric server
3. Start the server
4. On first launch, the mod generates a config file at config/mcrestapi.json and prints the master key and default API key to the server console. Save both keys immediately -- they cannot be retrieved later.
5. The API is available at http://localhost:8080 by default
6. The admin dashboard is at http://localhost:8080/admin

Configuration

The configuration file is located at config/mcrestapi.json and is generated automatically on first launch.

Field Type Default Description port integer 8080 Port the HTTP server listens on bindAddress string 127.0.0.1 Address to bind to. Use 0.0.0.0 for all interfaces maxConnections integer 50 Maximum concurrent HTTP connections swagger boolean true Enable/disable Swagger UI and OpenAPI spec masterKeyHash string (generated) PBKDF2 hash of the master key auth object (enabled) Set auth.enabled to false to delegate auth to a reverse proxy keys array (generated) List of API keys with permissions cors object (disabled) CORS configuration

API key hashes are stored using PBKDF2-SHA256. The raw key values are only shown once at creation time.

Authentication

All API endpoints (except public ones) require a Bearer token in the Authorization header:

Authorization: Bearer mcsapi_xxxxxxxxxxxxxxxx

The master key is generated on first launch and grants access to admin endpoints (/api/admin/*) and the dashboard (/admin). It also has wildcard permissions for all data endpoints.

Disabling authentication

If a reverse proxy already handles auth (basic auth, OIDC/forward-auth, etc.), set auth.enabled to false in the config:

{ "auth": { "enabled": false } }

This disables all authentication, including the admin endpoints — the reverse proxy becomes the only trust boundary. Only do this when bound to 127.0.0.1 behind a proxy that enforces access control. The mod logs a warning on startup (louder if the bind address is not loopback). You can also toggle it live from the dashboard (Settings → Require API Key), no restart required.

Permissions

Permission Description Endpoints server.read Read server stats GET /api/server players.read Read player list GET /api/players world.read Read world data GET /api/world chat.read Read event history GET /api/chat chat.stream Connect to SSE event stream GET /api/events/stream command.execute Execute server commands POST /api/command * All permissions (wildcard) All endpoints

API Endpoints

Base URL: http://<host>:<port> (default: http://localhost:8080)

For detailed request/response examples, see the built-in Swagger UI at /api/docs.

Public (no auth required)

Method Path Description GET /api/server/icon Server icon as PNG image GET /api/docs Swagger UI GET /api/openapi.json OpenAPI 3.1.0 spec

Data Endpoints

Method Path Permission Description GET /api/server server.read Server stats (TPS, MSPT, memory, CPU). Supports ?fields= filtering GET /api/players players.read Online player list with health, position, dimension, ping GET /api/world world.read Global world data and per-dimension stats. Supports ?fields= filtering GET /api/chat chat.read Event history. Supports ?limit= and ?type= filtering GET /api/events/stream chat.stream Real-time SSE stream. Supports ?types= filtering POST /api/command command.execute Execute a server command

Admin Endpoints (master key required)

Method Path Description GET /api/admin/keys List all API keys POST /api/admin/keys Create a new API key PUT /api/admin/keys?id= Update an API key DELETE /api/admin/keys?id= Revoke an API key GET /api/admin/cors Get CORS configuration POST /api/admin/cors Add an allowed origin PUT /api/admin/cors Toggle CORS enabled/disabled DELETE /api/admin/cors Remove an allowed origin GET /api/admin/settings Get current settings PUT /api/admin/settings Update settings

SSE Event Stream

Connect to /api/events/stream for real-time server events. Events are sent in standard SSE format. A keepalive ping is sent every 30 seconds.

Event types: chat, command, join, leave, death, game

For browser-based SSE connections, pass the API key via ?auth= query parameter since EventSource does not support custom headers.

CORS

CORS is disabled by default. When enabled, only origins in the allowlist receive CORS headers. Configure via the admin dashboard or /api/admin/cors endpoints.

CORS only provides protection in the browser context. It does not replace API key authentication.

Admin Dashboard

Built-in web dashboard at /admin (requires master key).

Pages: Dashboard (server stats), Players, World, Chat (live SSE stream), Console (command execution), Keys, CORS, Settings.

Security

• Default bind address is 127.0.0.1 (localhost only)
• API keys hashed with PBKDF2-SHA256 with random salt
• Master key stored separately from API keys
• For remote access, use a reverse proxy (nginx, Caddy) with HTTPS/TLS
• Create API keys with minimal permissions needed for each use case
• Only disable authentication when bound to 127.0.0.1 behind a trusted reverse proxy that enforces auth