Skip to content
Create Minecraft bots with a powerful, stable, and high level JavaScript API.
Branch: master
Clone or download
rom1504 Merge pull request #782 from PrismarineJS/greenkeeper/mocha-6.0.0
Update mocha to the latest version 🚀
Latest commit ddca43a Feb 19, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci move to circleci 2 Aug 26, 2018
docs Release 2.7.5 Feb 13, 2019
examples Merge pull request #569 from plexigras/fix-trader-example Sep 29, 2018
lib improve basic find block Feb 13, 2019
test fix a null which should be an undefined Sep 29, 2018
.gitignore change location of opping Sep 29, 2018


NPM version Build Status Discord Gitter Irc Greenkeeper badge

Create Minecraft bots with a powerful, stable, and high level JavaScript API.


  • Supports Minecraft 1.8, 1.9, 1.10, 1.11 and 1.12.
  • Entity knowledge and tracking.
  • Block knowledge. You can query the world around you.
  • Basic physics and movement - currently blocks are either "solid" or "empty".
  • Attacking entities and using vehicles.
  • Inventory management.
  • Crafting, chests, dispensers, enchantment tables.
  • Digging and building.
  • Miscellaneous stuff such as knowing your health and whether it is raining.
  • Activating blocks and using items.
  • Chat.


  • Brewing stands, and anvils.
  • Better physics (support doors, ladders, water, etc).


Without version specified, the version of the server will be guessed automatically, you can set a specific one using the version option. For example version:"1.8".

Echo Example

var mineflayer = require('mineflayer');
var bot = mineflayer.createBot({
  host: "localhost", // optional
  port: 25565,       // optional
  username: "", // email and password are required only for
  password: "12345678",          // online-mode=true servers
bot.on('chat', function(username, message) {
  if (username === bot.username) return;;


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

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

On windows :

set DEBUG=minecraft-protocol
node your_script.js

More Examples

Third Party Plugins

Mineflayer is pluggable; anyone can create a plugin that adds an even higher level API on top of Mineflayer.

Projects Using Mineflayer


npm install mineflayer



Please read


Some setup is required after first cloning the project but after that is done it's very easy to run them.


In order to get all tests to run successfully you must first:

  1. create a new folder in which to store minecraft server jars
  2. set the MC_SERVER_JAR_DIR to this folder


  1. mkdir server_jars
  2. export MC_SERVER_JAR_DIR=/full/path/to/server_jars

Where the "/full/path/to/" is the fully qualified path name.


Simply run: npm test

Updating to a newer protocol version

  1. Wait for a new version of node-minecraft-protocol to be released which supports the new Minecraft version.
  2. npm install --save minecraft-protocol@latest
  3. Apply the protocol changes where necessary.
  4. Run the test suite. See Testing above.



You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.