Skip to content

MineChat Protocol Specification

Version 1.0.0

1. Purpose

The MineChat Protocol defines a secure, binary-framed, compressed protocol that enables users to interact with a Minecraft server's chat system without being logged into Minecraft on the same device.

It uses a stateful, bidirectional, event-driven client-server model where the server is authoritative and clients declare their capabilities.

The protocol is designed to:

  • Support multiple external client devices per Minecraft account
  • Preserve Minecraft-compatible text formatting
  • Allow moderation at both per-device and per-account granularity
  • Operate without reliance on public Certificate Authorities
  • Be efficient, extensible, and implementation-agnostic

This specification defines wire-level behavior only. User interfaces, database schemas, command names, and server-side storage formats are explicitly out of scope.

2. Terminology and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

  • Client: An external MineChat client application.
  • Server: A MineChat server component integrated with a Minecraft server.
  • Linking: The process of associating a client device with a Minecraft account.
  • Client UUID: A UUID generated by the client to identify a specific device.
  • Minecraft UUID: The UUID of a Minecraft account.
  • RTT (Round-Trip Time): Time elapsed between sending a PING and receiving the corresponding PONG.

3. Transport and Security

3.1 TLS

All connections MUST be established over TLS.

  • Servers MUST present a self-signed TLS certificate.
  • Clients MUST perform certificate pinning after linking.
  • Public Certificate Authorities are NOT REQUIRED.

3.2 Certificate Pinning

  • During initial linking, the client stores the server's certificate or public key. No pin check is performed on that first connection.
  • A pin MAY be the SHA-256 digest of the DER-encoded peer certificate, or the SHA-256 digest of the DER-encoded SubjectPublicKeyInfo.
  • On subsequent connections, the client MUST reject the connection if the presented certificate does not match the pinned certificate.
  • Pin comparison is authoritative; implementations MUST NOT silently trust a changed certificate.
  • Behavior on certificate rotation is implementation-defined, but certificate mismatch MUST cause connection failure.
  • Hostname verification policy is implementation-defined, but a failed pin check MUST terminate the connection.

3.3 Default Port

The MineChat protocol does not require a fixed port number.

Implementations SHOULD use TCP port 7632 as the default when no explicit port is configured. The default port is provided for interoperability convenience and does not imply exclusivity.

Implementations MUST allow the port to be configurable.

Clients MUST NOT assume that a server is available on the default port and MUST allow users or configuration to specify an alternate port.

4. Framing Layer

All MineChat messages are transmitted using a length-prefixed binary framing format.

4.1 Frame Structure

Each frame consists of:

[4 bytes decompressed size]
[4 bytes compressed size]
[compressed payload bytes]

4.2 Integer Encoding

  • All framing integers MUST be:
  • 32-bit signed integers
  • Big-endian (network byte order)
  • Negative or zero sizes MUST terminate the connection

4.3 Semantics

  • decompressed size indicates the exact byte length after decompression.
  • compressed size indicates the byte length of the compressed payload.
  • Receivers MUST read exactly the specified number of bytes.
  • Decompression MUST produce exactly decompressed size bytes. A mismatched length or decompression failure MUST result in connection termination.
  • A stream ending before any byte of a frame has been read is a graceful disconnect.
  • A stream ending part-way through a frame header or payload MUST be treated as a protocol error and terminate the connection.

4.4 Connection Termination

Any event that results in session termination, including:

  • client disconnect,
  • server kick,
  • ban, or
  • fatal protocol error

MUST result in the immediate closure of the underlying TCP connection by at least one peer after any required final packet has been transmitted.

4.5 Resource Limits

Implementations MUST enforce implementation-defined limits on frame sizes and resource usage.

In particular:

  • The declared decompressed size and compressed size fields MUST be validated before allocating memory or attempting decompression.
  • Implementations SHOULD enforce limits primarily on the decompressed size to prevent excessive memory usage and denial-of-service attacks.
  • Implementations SHOULD impose a maximum decompressed size of 1 MiB (1,048,576 bytes) by default.
  • This limit is implementation-defined and MAY be configured differently depending on the deployment environment.
  • Frames whose declared sizes exceed the implementation's configured limits MUST be rejected.
  • Upon detecting such a violation, the implementation MUST terminate the connection.
  • Receivers MUST NOT attempt partial processing of frames that violate these limits.

This specification does not mandate specific size limits; implementations are expected to choose limits appropriate for their environment.

5. Compression

  • All payloads MUST be compressed using zstd.
  • Compression is mandatory and unconditional.
  • There is no negotiation for compression.
  • Compression is applied after CBOR serialization.

Pipeline:

CBOR encode → zstd compress → frame → TLS

6. CBOR Usage

6.1 General Rules

This specification defines semantic meaning for CBOR map keys within defined numeric ranges. These ranges are a MineChat protocol convention and are not imposed by CBOR itself. Implementations MUST interpret map keys according to this specification and MUST ignore unknown keys unless explicitly stated otherwise.

  • All payloads MUST be encoded as CBOR maps.
  • CBOR map keys are semantic identifiers, not ordered fields.
  • Implementations MUST NOT rely on map ordering.
  • Unknown keys MUST be ignored to allow extensibility.

6.2 Field Types

Unless otherwise stated:

Strings

  • Strings MUST be encoded as CBOR text strings (major type 3).
  • Strings MUST be valid UTF-8.
  • Implementations MUST reject strings containing invalid UTF-8 sequences.
  • Strings MUST NOT be encoded as CBOR byte strings (major type 2).
  • UUIDs MUST be encoded as UTF-8 text strings in canonical UUID format.

Integers

  • Integer fields MUST be encoded as CBOR integers.
  • Integer values MUST fit within a signed 64-bit integer range:
  • Minimum: -9,223,372,036,854,775,808
  • Maximum: 9,223,372,036,854,775,807
  • Implementations MUST reject values outside this range.
  • If a field requires a different bound, it will be explicitly defined in its packet specification.
  • Integer values MUST be treated as signed 64-bit integers in all implementations, regardless of the host language's native integer type.

6.3 Simplified CBOR Notation

This specification uses a simplified CBOR representation for readability, for example:

{
  0: 1,
  1: "hello"
}

This notation is illustrative only and represents a CBOR map, not JSON.

7. Packet Model

7.1 Packet Direction

Each packet is either:

  • Clientbound (Server → Client)
  • Serverbound (Client → Server)

Each packet MUST include a packet type identifier.

7.2 Common Packet Envelope

All packets share the following top-level structure:

{
  0: packet_type (int),
  1: payload (map)
}

7.3 Envelope Requirements

  • The top-level value MUST be a CBOR map.
  • Key 0 MUST be present and MUST be a CBOR integer packet type.
  • Key 1 MUST be present and MUST be a CBOR map.
  • Unknown top-level keys MUST be ignored.
  • Missing or malformed required envelope keys MUST terminate the connection.

7.4 Session Stages

A session moves through four stages. Each stage describes what the server already knows about the connected client, and how both interact.

  • Not linked. The connection is open, but the server does not know which client device or which Minecraft account is on the other end. The client sends LINK with a linking code. Nothing else is accepted at this stage.

  • Linked. The server has accepted the linking code and has replied with LINK_OK. The server now knows which Minecraft account this device belongs to. The client sends CAPABILITIES next.

  • Ready. The server has read and accepted the client's list of message formats and has replied with AUTH_OK. Both sides now know which formats they can use, and chat can flow.

  • Closed. The connection has ended. The server reads no further packets.

7.5 Packets Accepted at Each Stage

Packet Sent by Accepted at
LINK Client Not linked
LINK_OK Server Reply to an accepted LINK
CAPABILITIES Client Linked
AUTH_OK Server Reply to an accepted CAPABILITIES
CHAT_MESSAGE Both Ready
PING Both Any stage before Closed
PONG Both Any stage before Closed
MODERATION Server Ready
SYSTEM_DISCONNECT Server Any stage
Unknown packet type Either Any stage; ignored (§12)

7.6 Packets That Arrive Out of Order

A packet that arrives at the wrong stage is a protocol error. The receiver MUST close the connection.

Repeats count as out-of-order packets. A second LINK after the session is already linked is a protocol error. A second CAPABILITIES after the session is already ready is a protocol error.

PING and PONG are the only exception. They exist to check that the connection is still alive, so they are accepted at any point before the session ends.

8. Packet Types

Sent by the client during initial linking.

Packet Type: 0x01
Direction: Client → Server

Payload:

{
  0: linking_code (string),
  1: client_uuid (string)
}

Sent by the server when linking succeeds.

Packet Type: 0x02
Direction: Server → Client

Payload:

{
  0: minecraft_uuid (string)
}

8.3 CAPABILITIES (Serverbound)

Sent by the client immediately after linking or reconnecting.

Packet Type: 0x03
Direction: Client → Server

Payload:

{
  0: supported_formats (array of string),
  1: preferred_format (string) ; optional
}

Semantics

  • supported_formats declares the set of message formats the client is capable of receiving and MUST be a CBOR array of text strings. Format identifiers are case-sensitive and MUST be compared as exact byte-for-byte UTF-8 strings.

Each element in the array:

  • MUST be a CBOR text string (major type 3)
  • MUST contain a UTF-8 encoded format identifier
  • MUST NOT be empty
  • MUST NOT contain duplicates within the array

The array:

  • MUST NOT contain non-string values
  • MUST be non-empty
  • Each entry is a string identifier

Implementations MUST include "components" in this list.

This specification defines the following format identifiers:

  • "components":
  • JSON-encoded Minecraft Text Component (see Section 8.5)

  • This format is REQUIRED and represents the canonical message format of the protocol

  • "commonmark":

  • CommonMark Markdown text
  • Reference: https://commonmark.org/
  • Support for this format is RECOMMENDED

Clients MAY include additional format identifiers for extensions or implementation-defined formats.

  • preferred_format indicates the client’s preferred format for receiving messages.

Rules:

  • If present, preferred_format MUST be one of the values listed in supported_formats.
  • Servers SHOULD respect preferred_format when selecting a format for outgoing CHAT_MESSAGE packets.
  • Servers MAY ignore preferred_format based on implementation policy, compatibility, or message constraints.

The server answers with its own list and its choice in AUTH_OK. §8.4 defines how the two lists are combined.

  • Servers MUST reject a CAPABILITIES payload that does not include "components", by closing the connection without replying.

8.4 AUTH_OK (Clientbound)

Confirms that linking and format negotiation are complete. It also states which format the server has chosen.

Packet Type: 0x04
Direction: Server → Client

Payload:

{
  0: server_formats (array of string),
  1: selected_format (string)
}

Semantics

  • server_formats lists the formats the server is able to receive. It follows the same rules as supported_formats (§8.3): an array of unique, non-empty text strings, and it MUST include "components".
  • selected_format is the format the server will use for CHAT_MESSAGE packets it sends.

The two sides agree on a format by intersecting their lists. The agreed formats are the entries that appear in both supported_formats and server_formats.

Rules:

  • selected_format MUST be an agreed format.
  • Servers SHOULD select preferred_format when it is an agreed format.
  • Servers MAY select a different agreed format when the preferred one cannot represent a given message.
  • Servers MUST NOT send a CHAT_MESSAGE in a format that is not an agreed format.

Because both sides MUST include "components", two conforming implementations always share at least one format. An empty intersection means one side is not conforming.

Clients MUST use selected_format for anything they need to send, unless they send a format the server listed in server_formats.

8.5 CHAT_MESSAGE (Bidirectional)

Packet Type: 0x05
Direction: Client ↔ Server

Payload:

{
  0: format (string),
  1: content (string),
  2: source (string)
}

Format Semantics

  • format is a string identifier describing how content must be interpreted.

This specification defines:

  • "components":
  • content MUST be a UTF-8 string containing a JSON-encoded Minecraft Text Component
  • This format is mandatory and MUST be supported by all implementations
  • Based on the official text component format: https://minecraft.wiki/w/Text_component_format

  • Produced by Paper / Adventure: https://papermc.io/

  • "commonmark":

  • content is a UTF-8 string containing CommonMark Markdown
  • Support for this format is RECOMMENDED

Source Semantics

  • source indicates the origin of the message.
  • This field MUST be present in all CHAT_MESSAGE packets.
  • Valid values:
Value Meaning
"minechat" Message originated from a MineChat client
"minecraft" Message originated from a Minecraft player
  • Clients MAY use source to differentiate messages visually (e.g., prefixes, colors, icons).

Rules

  • Clients MUST support receiving "components" messages.

  • Servers MUST be able to send "components" messages.

  • Clients MAY send messages in any format listed in their CAPABILITIES.

  • Servers MUST NOT send a CHAT_MESSAGE in a format not declared in the client's supported_formats.

  • When multiple formats are supported by the client, the server SHOULD select the format indicated by preferred_format, if provided.

  • Servers MAY convert messages between formats as needed.

  • If a server cannot process a message format sent by the client, it MUST reject the message or ignore it according to implementation policy.

  • Servers MAY apply filtering, permissions, or routing logic when handling messages, provided that moderation rules defined in this specification are enforced.

  • The server MAY distribute a received message to zero or more connected clients (e.g., broadcast, filtering, or routing).

  • Clients MUST NOT assume that a sent message will be broadcast, echoed back, or delivered to any specific recipient.

  • The content field is always a UTF-8 CBOR text string, regardless of format.

  • Servers SHOULD, by default, broadcast messages to all authorized clients unless restricted by configuration or moderation.

8.6 PING (Bidirectional)

Packet Type: 0x06

Payload:

{
  0: timestamp_ms (int)
}
  • Represents milliseconds since the Unix epoch (1970-01-01T00:00:00Z).
  • The value MUST conform to the integer constraints defined in Section 6.2.
  • The timestamp MAY be generated using the sender's local clock.
  • The value MUST NOT be altered during transit.
  • The receiver MUST treat it as an opaque value for RTT calculation.

8.7 PONG (Bidirectional)

Packet Type: 0x07

Payload:

{
  0: timestamp_ms (int)
}

  • This packet is the response to a corresponding PING packet.

  • The timestamp_ms value MUST be identical to the value received in the PING packet.

  • The receiver MUST match PONG.timestamp_ms with the outstanding PING.timestamp_ms to measure RTT.

  • Receipt of a PONG with an unknown or unmatched timestamp_ms MAY be ignored.
  • The timestamp_ms value is echoed back unchanged in the corresponding PONG packet.
  • The timestamp_ms field MUST exactly match the value received in the corresponding PING.

8.8 MODERATION (Clientbound)

The MODERATION packet is used by the server to communicate and enforce moderation actions on client devices or Minecraft accounts.

Moderation actions are authoritative and MUST be enforced by the server as part of its session and message handling logic.

Packet Type: 0x08
Direction: Server → Client

Payload:

{
  0: action (int),           ; warn=0, mute=1, kick=2, ban=3
  1: scope (int),            ; client=0, account=1
  2: reason (string),        ; optional
  3: duration_seconds (int)  ; optional
}

Semantics

  • action defines the moderation action being applied.
  • scope determines whether the action applies to:
  • a specific client device (client=0), or
  • the associated Minecraft account (account=1).
  • reason and duration_seconds provide additional context and are optional.

MODERATION is independent of system lifecycle events and MUST NOT be used to signal server shutdown or maintenance.

Enforcement Rules

  • Servers MUST enforce moderation actions consistently across sessions according to the specified scope.

  • Mute:

  • Messages sent by the affected client MUST NOT be distributed to other clients.

  • Kick:

  • The server MUST terminate the connection after sending the MODERATION packet.

  • The server MAY follow up with a SYSTEM_DISCONNECT packet indicating the reason.

  • Ban:

  • The server MUST prevent the affected client or account from establishing new sessions while the ban is active.

  • If a banned client attempts to connect, the server MUST reject the connection.

  • Warn:

  • Has no direct enforcement effect on the connection.
  • Servers MAY log, notify, or apply additional policies internally.

Client Behavior

  • Clients MUST apply the received moderation action locally where applicable.
  • Clients MUST terminate the session upon receiving a kick or ban action that applies to their scope.
  • Clients MUST NOT attempt to bypass or ignore active moderation actions.

Scope Semantics

  • If scope = client, the action applies only to the current device session identified by its client_uuid.
  • If scope = account, the action applies to all client devices associated with the Minecraft account.

8.9 SYSTEM_DISCONNECT (Clientbound)

Packet Type: 0x09
Direction: Server → Client

Payload:

{
  0: reason_code (int),
  1: message (string)
}

The SYSTEM_DISCONNECT packet indicates that the server is intentionally terminating the connection due to a system-level lifecycle event, not a user-targeted moderation action.

Unlike MODERATION, this packet is not related to user behavior enforcement and MUST NOT be used for kicks, bans, mutes, or account-level penalties.

After sending SYSTEM_DISCONNECT, the server MUST immediately close the underlying TCP connection.

Clients MUST treat this packet as terminal and MUST NOT attempt reconnection automatically unless explicitly configured.

Reason Codes

Value Meaning
0 Shutdown
1 Maintenance
2 Internal error
3 Overloaded

Implementations MAY define additional codes in the 128+ range for private or experimental use.

Interaction with Keep-Alive

SYSTEM_DISCONNECT MAY be sent at any time.

After sending it:

  • server SHOULD stop sending further packets
  • server MUST close the connection immediately or after flushing pending frames

Clients receiving SYSTEM_DISCONNECT MUST NOT wait for PING/PONG timeout and MUST terminate immediately.

9. Keep-Alive

  • Default keep-alive interval: 15 seconds
  • Default keep-alive timeout: 30 seconds
  • Interval and timeout MAY be configurable.
  • Either side may send PING at any time.
  • Any received packet MUST reset the inactivity timer.
  • Failure to receive any packet within the timeout window MUST result in connection termination.

10. Packet Flow

This section walks through each exchange in order. Every step names who sends what, and what the other side does next.

10.1 Linking a Device

A player runs a link command on the Minecraft server. The server shows a short linking code. The player types that code into their MineChat client.

The client then opens a TLS connection to the MineChat server:

Player                  Server                Client
  |                       |                     |
  | /minechat link        |                     |
  |---------------------->|                     |
  |  linking code shown   |                     |
  |                       |                     |
  |                       |<--- TLS connect ----|
  |                       |---- TLS cert ------>|
  |                       |                     |
  |                       |<--- LINK -----------|
  |                       |---- LINK_OK --------|
  |                       |                     |
  |                       |<--- CAPABILITIES ---|
  |                       |---- AUTH_OK --------|

What happens at each step:

  1. The player runs the link command, and the Minecraft server shows a linking code.
  2. The client opens a TLS connection. The server presents its self-signed certificate.
  3. The client has no saved pin yet, so it accepts this certificate and saves a SHA-256 digest of it. Later connections are checked against the saved value (§3.2).
  4. The client sends LINK with the linking code and its own client UUID.
  5. The server checks the code. If the code is correct, the server sends LINK_OK with the Minecraft UUID, and the session moves to Linked. If the code is wrong, the server closes the connection.
  6. The client sends CAPABILITIES with the message formats it understands.
  7. The server chooses one format from that list, and sends AUTH_OK with its chosen format. The session is now Ready.

10.2 Declaring Message Formats

Client                         Server
  |                               |
  |--- CAPABILITIES ------------->|
  |                               |
  |<--- AUTH_OK ------------------|
  1. The client sends CAPABILITIES. It lists every format it understands, and optionally names one as its preferred format (§8.3).
  2. The server intersects that list with its own supported formats, and picks one.
  3. The server sends AUTH_OK. It reports its own list as server_formats, and its choice as selected_format (§8.4).
  4. The session is now Ready, and chat can flow.

Both sides list "components", so both sides can always reach each other. The client can now see which format the server chose, and whether its preferred format was honoured.

10.3 Sending a Chat Message

Client                         Server
  |                               |
  |--- CHAT_MESSAGE -------------->|
  |                               |
  |<-- CHAT_MESSAGE (broadcast) ---|
  1. The client sends CHAT_MESSAGE. It carries the format, the message text, and a source saying where the message came from (§8.5).
  2. The server applies moderation rules to the message.
  3. The server converts the message into a format each recipient understands.
  4. The server sends CHAT_MESSAGE to the clients it chooses. This may be every client, or only some of them.

The sender is not promised a copy of its own message. The server does not have to echo it back.

10.4 Answering a Keep-Alive Probe

Either side may send PING at any point. The other side replies with PONG and copies the timestamp unchanged (§9).

10.5 Ending a Session

There are two ways a session ends, and they are not the same thing.

A moderation decision. The server sends MODERATION. A kick ends the connection after the packet is sent. A ban is recorded and also blocks future sessions (§8.8).

A system event. The server sends SYSTEM_DISCONNECT and then closes the connection. Use this for shutdown, maintenance, internal errors, and overload. Do not use it for kicks or bans (§8.9).

Either way, the session ends and the connection closes (§4.4).

11. Security Considerations

  • TLS provides confidentiality and integrity.
  • Certificate pinning prevents MITM attacks.
  • Mandatory compression and framing prevent stream desynchronization.
  • Client UUIDs prevent trivial ban evasion.

12. Extensibility

  • Unknown packet types MUST be ignored.
  • Unknown CBOR fields MUST be ignored.
  • Packet type identifiers SHOULD be centrally documented.

Appendix A — Packet Reference Table

This section provides a single-glance reference for implementors. All packet structures are defined normatively in Section 8; this table is non-normative but authoritative.

Packet Type Table

Packet Name Type ID Direction Mandatory Purpose
LINK 0x01 Client → Server Yes Link client device to Minecraft account
LINK_OK 0x02 Server → Client Yes Confirm successful linking
CAPABILITIES 0x03 Client → Server Yes Declare client-supported features
AUTH_OK 0x04 Server → Client Yes Authentication complete
CHAT_MESSAGE 0x05 Client ↔ Server Yes Chat message transport
PING 0x06 Client ↔ Server Yes Keep-alive and RTT measurement
PONG 0x07 Client ↔ Server Yes Response to PING
MODERATION 0x08 Server → Client Optional Enforce moderation actions
SYSTEM_DISCONNECT 0x09 Server → Client Yes System-level disconnection

Packet Field Reference

Key Name Type Required
0 linking_code string Yes
1 client_uuid string Yes
Key Name Type Required
0 minecraft_uuid string Yes

CAPABILITIES (0x03)

Key Name Type Required
0 supported_formats array of string Yes
1 preferred_format string No

AUTH_OK (0x04)

Key Name Type Required
0 server_formats array of string Yes
1 selected_format string Yes

Valid selected_format values:

Value Meaning
commonmark CommonMark Markdown
components JSON-encoded Minecraft Text Component

Both sides MUST include "components". selected_format MUST appear in both server_formats and the client's supported_formats.

CHAT_MESSAGE (0x05)

Key Name Type Required
0 format string Yes
1 content string Yes
2 source string Yes

Valid format values:

Value Meaning
commonmark CommonMark Markdown
components JSON-encoded Minecraft Text Component

Valid source values:

Value Meaning
"minechat" Message originated from a MineChat client
"minecraft" Message originated from a Minecraft player

PING (0x06)

Key Name Type Required Notes
0 timestamp_ms int Yes Milliseconds since Unix epoch

PONG (0x07)

Key Name Type Required Notes
0 timestamp_ms int Yes Must match corresponding PING value

MODERATION (0x08)

Key Name Type Required
0 action int Yes
1 scope int Yes
2 reason string No
3 duration_seconds int No

Action values:

Value Meaning
0 Warn
1 Mute
2 Kick
3 Ban

Scope values:

Value Meaning
0 Client UUID
1 Minecraft UUID

Appendix B — Numeric Range Reservations

This section is normative.

Packet Type ID Ranges

Range Reservation
0x00 Reserved (invalid)
0x01-0x1F Core protocol packets (this spec)
0x20-0x3F Future protocol extensions
0x40-0x7F Experimental / non-standard
0x80-0xFF Implementation-private

Rules:

  • Core protocol packets MUST use IDs in 0x01-0x1F
  • Implementations MUST NOT redefine core packet IDs
  • Experimental packets MUST NOT be required for interoperability
  • Private packets MUST NOT be sent unless both sides explicitly support them

CBOR Map Key Ranges

CBOR map keys inside packet payloads follow this reservation:

Key Range Meaning
0-31 Core fields (this spec)
32-63 Reserved for future core extensions
64-127 Optional extensions
128+ Implementation-defined

Rules:

  • Core fields MUST use keys 0-31
  • Unknown keys MUST be ignored
  • Implementations MUST NOT assume key ordering