MCRestAPI

# 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 (https://github.com/Natxo09/mcrestapi/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: ```json { "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 |