Minecraft NPC is a CLI for running NPC bot on Minecraft, powered by Mineflayer.
npm install mineflayer-chatgpt
Create a configuration file, e.g. minecraft-npc.yaml
Start Minecraft NPC bot:
minecraft-npc start --conf-file minecraft-npc.yaml
| Property | Description | Mandatory/Optional | Default Value |
|---|---|---|---|
| host | Minecraft server host | Optional | localhost |
| port | Minecraft server port | Optional | 25565 |
| version | Minecraft version | Mandatory | |
| viewer_port | Minecraft viewer port | Optional | 3000 |
| web_inventory_port | Minecraft web inventory port | Mandatory | |
| username | Minecraft username | Optional | bob |
| password | Minecraft password | Optional, only needed on online mode | |
| init_coords | Initial bot coordinates [x, y, z] | Optional | [0, 0, 0] |
| init_messages | Initial bot messages to send on spawn | Optional | |
| chatgpt_apikey | ChatGPT API key | Optional, only needed for ChatGPT chat feature | |
| chatgpt_model | ChatGPT model to use | Optional | gpt-5.2 |
| chatgpt_instructions | ChatGPT bot instructions | Optional |
To enable debug logs at protocol level, set DEBUG="minecraft-protocol" environment variable when running minecraft-npc. You'll get more detailed information when the program exits due to an error:
Spawning bot...
minecraft-protocol writing packet handshaking.set_protocol +0ms
minecraft-protocol {
minecraft-protocol protocolVersion: 763,
minecraft-protocol serverHost: 'somehost',
minecraft-protocol serverPort: 25565,
minecraft-protocol nextState: 2
minecraft-protocol } +1ms
minecraft-protocol writing packet login.login_start +48ms
minecraft-protocol {
minecraft-protocol username: 'someusername',
minecraft-protocol signature: null,
minecraft-protocol playerUUID: 'd3afe860-c1dd-3d13-8ec6-8680489964b0'
minecraft-protocol } +0ms
minecraft-protocol read packet login.disconnect +370ms
minecraft-protocol {
minecraft-protocol "reason": "{\"translate\":\"multiplayer.disconnect.incompatible\",\"with\":[\"1.20.4\"]}"
minecraft-protocol } +1ms
Bot has been kicked:
"{\"translate\":\"multiplayer.disconnect.incompatible\",\"with\":[\"1.20.4\"]}"
Build reports: