--- /dev/null
+++ b/docs/configuration/inbound/minecraft.md
@@ -0,0 +1,118 @@
+### Structure
+
+```json
+{
+  "type": "minecraft",
+  "tag": "mc-in",
+
+  ... // Listen Fields
+
+  "users": [
+    {
+      "username": "Steve",
+      "password": "my-secret-password"
+    }
+  ],
+  "status": {
+    "forward": false,
+    "version": {
+      "name": "1.20.4",
+      "protocol": 765
+    },
+    "description": "A Minecraft Server",
+    "players": {
+      "max": 20,
+      "online": 1,
+      "sample": [
+        {
+          "name": "Notch",
+          "id": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
+        }
+      ]
+    },
+    "favicon": "data:image/png;base64,<data>",
+    "enforces_secure_chat": false
+  },
+  "fallback": {
+    "server": "mc.example.com",
+    "server_port": 25565,
+    "tag": "mc-fallback"
+  }
+}
+```
+
+### Listen Fields
+
+See [Listen Fields](/configuration/shared/listen/) for details.
+
+### Fields
+
+#### users
+
+List of users allowed to authenticate through the proxy. Each entry has a `username` and `password`.
+
+Connections from usernames not in this list are forwarded to the `fallback` server (if configured), allowing real Minecraft players to connect transparently.
+
+#### status
+
+Controls the server list ping response shown to Minecraft clients.
+
+##### status.forward
+
+If `true`, status pings are forwarded to the `fallback` server instead of being answered locally. Requires `fallback` to be configured.
+
+##### status.version
+
+The version info shown in the server list.
+
+- `name`: Version string (e.g. `"1.20.4"`)
+- `protocol`: Protocol number (e.g. `765`). Defaults to `765` (1.20.4).
+
+##### status.description
+
+The MOTD shown in the server list. Accepts either a plain string or a [JSON Chat Component](https://wiki.vg/Text_formatting#JSON_text_component) object for rich formatting:
+
+```json
+"description": "A plain text MOTD"
+```
+
+```json
+"description": {"text": "A colored MOTD", "color": "green"}
+```
+
+##### status.players
+
+- `max`: Maximum player count shown.
+- `online`: Online player count shown.
+- `sample`: Player list shown on hover. Each entry has `name` and optionally `id` (UUID). If `id` is omitted, a deterministic offline UUID is generated from the name.
+
+##### status.favicon
+
+Server icon in `data:image/png;base64,<data>` format, shown in the server list.
+
+##### status.enforces_secure_chat
+
+Whether the server enforces signed chat messages. Passed through to the client as-is.
+
+#### fallback
+
+If configured, connections from unknown users are proxied transparently to this Minecraft server via the sing-box router.
+
+- `server`: Hostname or IP of the fallback server.
+- `server_port`: Port of the fallback server. Defaults to `25565`.
+- `tag`: When set, fallback connections are identified by this tag in routing metadata, allowing routing rules to send fallback traffic through a different outbound than proxy traffic.
+
+### Description
+
+The Minecraft inbound disguises proxy traffic as Minecraft Java Edition protocol traffic.
+
+The connection flow is:
+
+1. Client connects and sends a Minecraft handshake packet
+2. If the next state is **Status**: the server responds with a fake server list ping (or forwards to fallback if `status.forward` is enabled)
+3. If the next state is **Login**: the server performs the standard Minecraft encryption handshake (RSA key exchange + AES/CFB8)
+4. Authentication is verified by deriving a shared secret from `SHA-256(password + verify_token)[:16]`; real Minecraft clients naturally fail this check and receive an authentic "Failed to verify username!" error
+5. After login, smux multiplexing runs over the AES/CFB8 encrypted connection
+6. Each smux stream carries a 1-byte command (`0x01` for TCP, `0x03` for UDP) followed by a SOCKS address header
+
+Legacy pre-1.7 pings (`0xFE`) are also handled and return a correctly formatted response.