# Mineflayer: A JavaScript API for Minecraft Bots, From 1.8 to 26.1

> Mineflayer gives Node.js developers a high level API for building Minecraft bots, covering movement, inventory, crafting and chat across a wide version range. The interesting question is not whether it works, but where its abstraction stops and you are back to writing protocol-level code.

**PrismarineJS/mineflayer** — Create Minecraft bots with a powerful, stable, and high level JavaScript API.

- Repository: https://github.com/PrismarineJS/mineflayer
- Website: https://prismarinejs.github.io/mineflayer/
- Stars: 7,518 · Forks: 1,509
- Language: JavaScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/prismarinejs-mineflayer

## The gap Mineflayer fills between a raw protocol client and a game-playing bot

Writing a Minecraft client means parsing packets, tracking entities, simulating physics and keeping a local model of the world. Mineflayer sits above that layer and exposes the result as JavaScript objects. The README lists what that includes: entity knowledge and tracking, block knowledge with a queryable world, physics and movement with bounding boxes, attacking entities and using vehicles, inventory management, crafting and containers such as chests, dispensers and enchantment tables, digging and building, and chat.

The audience is narrow and specific. You are a Node.js developer who wants a program to join a server and do something inside it, whether that is a chat relay, a farm, a test harness for a server plugin, or a research toy. The README also notes the API is usable from Python, and links Python examples plus a Google Colab notebook, so the audience is not strictly JavaScript-only. If you want a graphical bot you click to configure, this is the wrong layer entirely.

## How Mineflayer is put together: protocol, world model, and a plugin surface

The dependency list in package.json is the clearest description of the architecture. Mineflayer does not implement the Minecraft protocol itself; it depends on minecraft-protocol. It does not define block, item, entity or recipe data; it pulls those from minecraft-data and the prismarine-* packages (prismarine-block, prismarine-entity, prismarine-item, prismarine-chunk, prismarine-world, prismarine-physics, prismarine-recipe, prismarine-windows, prismarine-biome, prismarine-registry, prismarine-chat, prismarine-nbt).

That split matters when you debug. A wrong block ID or a missing item is a minecraft-data problem. A connection or handshake failure is a minecraft-protocol problem. Mineflayer's own job is to wire those pieces into one bot object and emit events.

The event model is the part you actually program against. The README's echo example listens for a chat event, filters out the bot's own messages by comparing against bot.username, and calls bot.chat to send the message back. The same example registers handlers for kicked and error, which the README describes as logging errors and kick reasons. Anything beyond that comes from the API reference or from plugins, and the related search terms around mineflayer plugins and mineflayer-pathfinder reflect how much of real bot behaviour lives outside the core package.

## Installing Mineflayer and running a first bot that echoes chat

The README says to install Node.js first, and package.json sets the engine requirement to Node.js 22 or newer. The README text itself says Node.js >= 18, so the two sources disagree; the package.json engines field is the stricter of the two and is the one npm will enforce. Then install the package:

```bash
npm install mineflayer
```

A minimal bot needs a host, a username and an auth mode. The README's echo example passes host, username and auth, with port, version and password shown as commented-out options. Without a version specified, the README states the server version is guessed automatically, and without auth specified the Mojang auth style is guessed.

```js
const mineflayer = require('mineflayer')

const bot = mineflayer.createBot({
  host: 'localhost',
  username: 'Bot',
  auth: 'microsoft'
})

bot.on('chat', (username, message) => {
  if (username === bot.username) return
  bot.chat(message)
})
```

Run that with node and, on a server where the account is allowed, the bot joins and repeats chat messages it sees. If you set auth to 'microsoft', the README states you will be prompted to log in at microsoft.com with a code in your browser, and that tokens are cached afterwards so you do not sign in again. The README says cached tokens go in your user's .minecraft folder by default, or in profilesFolder when that option is given. To switch accounts, change the username.

For offline-mode servers the README says to set auth to 'offline'. To see what the bot is doing, the README points at prismarine-viewer, installed with npm install prismarine-viewer, which displays the bot's view in a browser window.

```bash
npm install prismarine-viewer
```

To update the package and its dependencies later, the README gives npm update.

## Version coverage is broad, and that breadth is also the maintenance cost

The README claims support for Minecraft 1.8 through 26.1, listing 1.8, 1.9, 1.10, 1.11, 1.12, 1.13, 1.14, 1.15, 1.16, 1.17, 1.18, 1.19, 1.20, 1.21, 1.21.9, 1.21.11 and 26.1. That is a lot of protocol surface to keep working, and it explains why the version option exists in the bot config: you set it when automatic detection guesses wrong, which the README's comment describes as being for a specific version or snapshot.

The practical consequence is that bugs are version-specific. A behaviour that works on one server release may not hold on another, and the repository's test setup reflects this: the devDependencies include minecraft-wrap, which is used to run real Minecraft server versions in tests. If you are targeting a single server version, pin it explicitly in the bot options rather than relying on detection, and check the changelog in history.md before upgrading, since releases ship frequently. The most recent releases listed are 4.39.0, 4.38.0 and 4.37.1, and the repository's last push was on 2026-09-21.

## Where Mineflayer stops: pathfinding, combat, and server-side rules

Mineflayer gives you primitives, not behaviour. The README's feature list includes physics and movement, but that is not the same as knowing how to walk from one place to another around obstacles. Pathfinding is a separate concern that the ecosystem addresses through plugins, which is why mineflayer-pathfinder appears as a related search term rather than as a dependency in package.json. If you expect createBot to produce a bot that navigates a cave, you will be disappointed.

The second limitation is external. Server-side anti-cheat, plugin rules and account policies are outside Mineflayer's control, and the README says nothing about them. A bot that behaves correctly by the library's standards can still be kicked, which is why the echo example registers a kicked handler at all. Do not read the feature list as a statement about what any particular server will permit.

The third is authentication. The README describes password-based auth as possibly unreliable, and notes that when a password is used the username must be an email. Microsoft auth requires a browser step the first time. For unattended deployments, that first login is a manual step you have to plan for, and the caching behaviour means the token store location matters if you run more than one bot.

## Mineflayer compared with writing against minecraft-protocol directly

The honest alternative is not another bot framework; it is the layer underneath. Mineflayer depends on minecraft-protocol and the prismarine-* packages, and you can use those directly. The difference is what you get for free. With minecraft-protocol you handle the connection, authentication and packet stream, and you decide what to do with each packet. With Mineflayer you get a world model already built from those packets: blocks you can query, entities that are tracked, an inventory abstraction, physics, and a chat event.

The trade-off runs the other way too. Anything Mineflayer does not model, you cannot reach without dropping down, and the README acknowledges this by linking an unstable_api.md alongside the main api.md. If your goal is a packet-level experiment, such as testing how a server reacts to a malformed sequence, Mineflayer's abstractions are overhead. If your goal is a bot that mines, crafts and talks, writing that against raw packets means rebuilding most of what Mineflayer already ships.

## Licence and upgrade cost

Mineflayer is MIT licensed, stated in both the README badge area and the license field in package.json, with the LICENSE file at the repository root. MIT is permissive: you can use, modify and redistribute it, including in closed-source projects, provided the licence and copyright notice are preserved. That covers the library itself. It does not cover Minecraft, Mojang's terms, or the rules of whatever server you connect to, and those are separate questions this repository does not address. Nothing here is legal advice; read the LICENSE file and the terms that apply to your use.

Upgrade cost is real because the dependency chain is wide. package.json lists roughly eighteen runtime dependencies, most of them versioned with caret ranges, so npm update can move minecraft-data and the prismarine-* packages at the same time as Mineflayer. The README gives npm update as the update command, and history.md as the changelog. The engines field requires Node.js 22 or newer, so an upgrade can also force a runtime upgrade. If you pin behaviour to a specific Minecraft version, pin the dependency versions too rather than letting caret ranges float.

## Conclusion

Adopt Mineflayer when you need scripted Minecraft automation in JavaScript and can accept that behaviour depends on the server version and on plugins you add yourself. Do not adopt it if you want a finished bot with pathfinding and combat out of the box, or if you need a guarantee about how a specific server will treat your client. Before writing anything, check the Node.js engine requirement in package.json against your runtime, confirm the version string for your target server, and read the FAQ file in the repository, which the README points to before the full API reference.

## FAQ

### What is Mineflayer used for?

It is a JavaScript library for creating Minecraft bots. The README lists entity and block knowledge, physics and movement, attacking and vehicles, inventory management, crafting and containers, digging and building, and chat as the capabilities it exposes.

### Is Mineflayer still actively developed?

The repository is not archived and its last push was on 2026-09-21. The most recent releases listed are 4.39.0, 4.38.0 and 4.37.1.

### What programming language is Mineflayer?

Mineflayer is written in JavaScript and is published on npm as the mineflayer package. The README also states the API is usable from Python and links Python examples.

### Is Mineflayer free?

Yes. The project is MIT licensed, with the licence stated in package.json and a LICENSE file at the repository root.

### How do I install Mineflayer?

Install Node.js first, then run npm install mineflayer. The package.json engines field requires Node.js 22 or newer, while the README text says Node.js >= 18.

### What is Mineflayer?

Mineflayer is a Node.js library that creates Minecraft bots through a high level JavaScript API, and the README states it is also usable from Python.

## Sources

- [License: MIT](https://github.com/PrismarineJS/mineflayer/blob/master/LICENSE)
- [PrismarineJS/mineflayer on GitHub](https://github.com/PrismarineJS/mineflayer)
- [Project website](https://prismarinejs.github.io/mineflayer/)
- [README](https://github.com/PrismarineJS/mineflayer/blob/master/README.md)
- [Releases](https://github.com/PrismarineJS/mineflayer/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/prismarinejs-mineflayer