Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Parse and serialize minecraft packets, plus authentication and encryption.

minecraft protocol

NPM version Build Status Join the chat at

Parse and serialize minecraft packets, plus authentication and encryption.


  • Supports Minecraft version 1.8.1
  • Parses all packets and emits events with packet fields as JavaScript objects.
  • Send a packet by supplying fields as a JavaScript object.
  • Client
    • Authenticating and logging in
    • Encryption
    • Compression
    • Both online and offline mode
    • Respond to keep-alive packets.
    • Ping a server for status
  • Server
    • Online/Offline mode
    • Encryption
    • Compression
    • Handshake
    • Keep-alive checking
    • Ping status
  • Robust test coverage. See Test Coverage section below.
  • Optimized for rapidly staying up to date with Minecraft protocol updates.

Projects Using node-minecraft-protocol

  • mineflayer - create minecraft bots with a stable, high level API.
  • mcserve - runs and monitors your minecraft server, provides real-time web interface, allow your users to create bots.


Echo client example

var mc = require('minecraft-protocol');
var client = mc.createClient({
  host: "localhost",   // optional
  port: 25565,         // optional
  username: "",
  password: "12345678",
client.on('chat', function(packet) {
  // Listen for chat messages and echo them back.
  var jsonMsg = JSON.parse(packet.message);
  if (jsonMsg.translate == 'chat.type.announcement' || jsonMsg.translate == 'chat.type.text') {
    var username = jsonMsg.using[0];
    var msg = jsonMsg.using[1];
    if (username === client.username) return;
    client.write(0x03, {
      message: msg

If the server is in offline mode, you may leave out the password option.

Hello World server example

var mc = require('minecraft-protocol');
var server = mc.createServer({
  'online-mode': true,   // optional
  encryption: true,      // optional
  host: '',       // optional
  port: 25565,           // optional
server.on('login', function(client) {
  client.write('login', {
    levelType: 'default',
    gameMode: 0,
    dimension: 0,
    difficulty: 2,
    maxPlayers: server.maxPlayers
  client.write('position', {
    x: 0,
    y: 1.62,
    z: 0,
    yaw: 0,
    pitch: 0,
    onGround: true
  var msg = { translate: 'chat.type.announcement', using: [
    'Hello, ' + client.username
  client.write(0x03, { message: JSON.stringify(msg) });


npm install minecraft-protocol

URSA, an optional dependency, should improve login times for servers. However, it can be somewhat complicated to install.

Follow the instructions from Obvious/ursa

Documentation, callback)

callback(err, pingResults)


Old version

  • prefix
  • protocol
  • version
  • motd
  • playerCount
  • maxPlayers

New version

  • description
  • players
    • max
    • online
    • sample
      • id
      • name
  • version
    • name
    • protocol
  • favicon
  • latency


Returns a Server instance and starts listening.



This is a plain old JavaScript object. Add a key with the username you want to be exempt from online mode or offline mode (whatever mode the server is in).

Make sure the entries in this object are all lower case.


Javascript object mapping a Client from a clientId.


The amount of players currently present on the server.


The maximum amount of players allowed on the server.


The motd that is sent to the player when he is pinging the server


A base64 data string representing the favicon that will appear next to the server on the mojang client's multiplayer list.


Returns a Client instance and perform login



The internal state that is used to figure out which protocol state we are in during packet parsing. This is one of the protocol.states.


True if this is a connection going from the server to the client, False if it is a connection from client to server.


Returns the internal nodejs Socket used to communicate with this client.


A string representation of the client's UUID. Note that UUIDs are unique for each players, while playerNames, as of 1.7.7, are not unique and can change.


The user's username.


The user's session, as returned by the Yggdrasil system.

Not Immediately Obvious Data Type Formats

Note : almost all data formats can be understood by looking at the packet structure in lib/protocol.js


Value looks like this:

  {type: 'slot', value: slot, key: 3},
  {type: 'int', value: value, key: 4},

Where the key is the numeric metadata key and the value is the value of the correct data type.


  • Ensure your system has the java executable in PATH.
  • Download the appropriate version of minecraft_server.jar.
  • MC_SERVER_JAR=path/to/minecraft_server.jar MC_PASSWORD=password npm test

Test Coverage

    ✓ handshaking,ServerBound,0x00
    ✓ status,ServerBound,0x00
    ✓ status,ServerBound,0x01
    ✓ status,ClientBound,0x00
    ✓ status,ClientBound,0x01
    ✓ login,ServerBound,0x00
    ✓ login,ServerBound,0x01
    ✓ login,ClientBound,0x00
    ✓ login,ClientBound,0x01
    ✓ login,ClientBound,0x02
    ✓ login,ClientBound,0x03
    ✓ play,ServerBound,0x00
    ✓ play,ServerBound,0x01
    ✓ play,ServerBound,0x02
    ✓ play,ServerBound,0x03
    ✓ play,ServerBound,0x04
    ✓ play,ServerBound,0x05
    ✓ play,ServerBound,0x06
    ✓ play,ServerBound,0x07
    ✓ play,ServerBound,0x08
    ✓ play,ServerBound,0x09
    ✓ play,ServerBound,0x0a
    ✓ play,ServerBound,0x0b
    ✓ play,ServerBound,0x0c
    ✓ play,ServerBound,0x0d
    ✓ play,ServerBound,0x0e
    ✓ play,ServerBound,0x0f
    ✓ play,ServerBound,0x10
    ✓ play,ServerBound,0x11
    ✓ play,ServerBound,0x12
    ✓ play,ServerBound,0x13
    ✓ play,ServerBound,0x14
    ✓ play,ServerBound,0x15
    ✓ play,ServerBound,0x16
    ✓ play,ServerBound,0x17
    ✓ play,ServerBound,0x18
    ✓ play,ServerBound,0x19
    ✓ play,ClientBound,0x00
    ✓ play,ClientBound,0x01
    ✓ play,ClientBound,0x02
    ✓ play,ClientBound,0x03
    ✓ play,ClientBound,0x04
    ✓ play,ClientBound,0x05
    ✓ play,ClientBound,0x06
    ✓ play,ClientBound,0x07
    ✓ play,ClientBound,0x08
    ✓ play,ClientBound,0x09
    ✓ play,ClientBound,0x0a
    ✓ play,ClientBound,0x0b
    ✓ play,ClientBound,0x0c
    ✓ play,ClientBound,0x0d
    ✓ play,ClientBound,0x0e
    ✓ play,ClientBound,0x0f
    ✓ play,ClientBound,0x10
    ✓ play,ClientBound,0x11
    ✓ play,ClientBound,0x12
    ✓ play,ClientBound,0x13
    ✓ play,ClientBound,0x14
    ✓ play,ClientBound,0x15
    ✓ play,ClientBound,0x16
    ✓ play,ClientBound,0x17
    ✓ play,ClientBound,0x18
    ✓ play,ClientBound,0x19
    ✓ play,ClientBound,0x1a
    ✓ play,ClientBound,0x1b
    ✓ play,ClientBound,0x1c
    ✓ play,ClientBound,0x1d
    ✓ play,ClientBound,0x1e
    ✓ play,ClientBound,0x1f
    ✓ play,ClientBound,0x20
    ✓ play,ClientBound,0x21
    ✓ play,ClientBound,0x22
    ✓ play,ClientBound,0x23
    ✓ play,ClientBound,0x24
    ✓ play,ClientBound,0x25
    ✓ play,ClientBound,0x26
    ✓ play,ClientBound,0x27
    ✓ play,ClientBound,0x28
    ✓ play,ClientBound,0x29
    ✓ play,ClientBound,0x2a
    ✓ play,ClientBound,0x2b
    ✓ play,ClientBound,0x2c
    ✓ play,ClientBound,0x2d
    ✓ play,ClientBound,0x2e
    ✓ play,ClientBound,0x2f
    ✓ play,ClientBound,0x30
    ✓ play,ClientBound,0x31
    ✓ play,ClientBound,0x32
    ✓ play,ClientBound,0x33
    ✓ play,ClientBound,0x34
    ✓ play,ClientBound,0x35
    ✓ play,ClientBound,0x36
    ✓ play,ClientBound,0x37
    ✓ play,ClientBound,0x38
    ✓ play,ClientBound,0x39
    ✓ play,ClientBound,0x3a
    ✓ play,ClientBound,0x3b
    ✓ play,ClientBound,0x3c
    ✓ play,ClientBound,0x3d
    ✓ play,ClientBound,0x3e
    ✓ play,ClientBound,0x3f
    ✓ play,ClientBound,0x40
    ✓ play,ClientBound,0x41
    ✓ play,ClientBound,0x42
    ✓ play,ClientBound,0x43
    ✓ play,ClientBound,0x44
    ✓ play,ClientBound,0x45
    ✓ play,ClientBound,0x46
    ✓ play,ClientBound,0x47
    ✓ play,ClientBound,0x48
    ✓ play,ClientBound,0x49

    ✓ pings the server (65754ms)
    ✓ connects successfully - online mode (STUBBED)
    ✓ connects successfully - offline mode (STUBBED)
    ✓ gets kicked when no credentials supplied in online mode (67167ms)
    ✓ does not crash for 10000ms (69597ms)

    ✓ starts listening and shuts down cleanly
    ✓ kicks clients that do not log in (133ms)
    ✓ kicks clients that do not send keepalive packets (122ms)
    ✓ responds to ping requests
    ✓ clients can log in and chat (39ms)
    ✓ kicks clients when invalid credentials (8430ms)
    ✓ gives correct reason for kicking clients when shutting down (42ms)

  123 tests complete (4 minutes)


You can enable some protocol debugging output using NODE_DEBUG environment variable:

NODE_DEBUG="minecraft-protocol" node [...]



  • Added hook to modify server ping (thanks Brian Schlenker)
  • Exposed the Client class to the browser, after removing node-specific details
  • Fixed the examples
  • Silenced the "DID NOT PARSE THE WHOLE THING" debug message, and made it print more useful info
  • Updated ursa-purejs dependency, which in turned fixed windows version of node-minecraft-protocol.


  • Fixed readPosition for negative packets (thanks rom1504)


  • Fixed particle packet.
  • Fixed release. 0.13.1 release was missing an entire folder.


  • Externalized rsa-wrap library to its own npm module, named ursa-native
  • Fixed broken bed-related packets (thanks rom1504)


  • Updated protocol version to support 1.8.1 (thanks wtfaremyinitials)
  • Lots of changes in how some formats are handled.
  • Crypto now defaults to a pure-js library if URSA is missing, making the lib easier to use on windows.
  • Fix a bug in yggdrasil handling of sessions, making reloading a session impossible (thanks Frase)
  • Set noDelay on the TCP streams, making the bot a lot less laggy.


  • Fix for/in used over array, causing glitches with augmented Array prototypes (thanks pelikhan)


  • Updated protocol version to support 1.7.10
  • Some bug fixes in parser (thanks Luke Young)
  • 'raw' event to catch all raw buffers (thanks deathcap)
  • Misc bug fixes


  • Updated protocol version to support 1.7.6


  • Updated protocol version to support 1.7.2
  • Overhaul the serializer backend to be more general-purpose and future-proof.
  • Support listening packets by name (thanks deathcap)
  • Support reading/writing a raw buffer to the socket.


  • Updated protocol version to support 1.6.4 (thanks Matt Bell)




  • packet 0x2c: packet writing fixed, UUID format simplified, tests updated


  • 1.6.2 support fixes: updated 0x2c packets to include elementList and added 0x85 Tile Editor Open packets


  • support minecraft protocol 1.6.2 / protocol version 74 (thanks Matt Bell)


  • support minecraft protocol 1.6.1 / protocol version 73 (thanks Matt Bell)
    • note: chat packets have a new format (see the examples for how to upgrade).


  • support minecraft protocol 1.5.2 / protocol version 61


  • Added SRV record support when connecting to a server (thanks Matt Stith)
  • 0x66: shift renamed to mode and changed from bool to byte





  • support minecraft protocol 1.5 / protocol version 60 (thanks Matt Bell)


  • server: ability to change motd and maxPlayers
  • server: fix incorrect playerCount


  • server: fix crash when client disconnects quickly


  • onlineModeExceptions are all lowercase now. fixes security hole.


  • server: add onlineModeExceptions. When server is in:
    • online mode: these usernames are exempt from online mode.
    • offline mode: these usernames must authenticate.


  • server: online mode: don't log in client until username verification


  • revert removing socket delays to reduce latency as it was causing errors and test failures.
  • server: Client now emits more predictable 'end' events.


  • fix objectData writer. This fixes sending an 0x17 packet.


  • remove socket delays to reduce latency. (thanks Matt Bell)


  • createServer: rename encryption-enabled option to encryption to stay consistent with the examples. (thanks Robin Lambertz)
  • createClient: don't require both email and username.
    • The username and password arguments are used to authenticate with the official minecraft servers and determine the case-correct username. If you have migrated your user account to a mojang login, username looks like an email address.
    • If you leave out the password argument, username is used to connect directly to the server. In this case you will get kicked if the server is in online mode.


Emit 'error' event instead of crashing when other computers abuse the minecraft protocol.

Big thanks to Robin Lambertz for this release.


  • ping: fix calling callback twice when server sends kick
  • server: send a kick packet when kicking clients. (thanks Robin Lambertz)
  • ping: include latency property (thanks Jan Buschtöns)


  • createServer: allow empty options
  • server: support online mode and encryption (thanks Robin Lambertz)


  • Allow minecraft username instead of mojang email. (thanks Robin Lambertz)


  • y values when only 1 byte are always unsigned


  • 0x0e: change face to unsigned byte


  • 0x0d: fix incorrectly swapped stance and y
Something went wrong with that request. Please try again.