Minecraft Bot Client

A pure-protocol Minecraft bot client written in Python. No client jar, no assets, no launcher — it speaks the protocol directly and drops you into an interactive console.

Download v2.1.0 Source code

Offline mode — built for servers running online-mode=false. Testing and development use.

MinecraftBotClient-en

Minecraft Bot Client (MBC) v2.1.0
all Minecraft versions 1.8 - 26.2
 
[verify]  remote 2.1.0, up to date
[player]  Steve_7f2a
[connect] mc.example.com:25565
[login]   connected · 1.20.6 · protocol 765
 
> .wal
  .walk start   .walk stop   .walk add   .walk list
 
> .walk add 0,64,0
[walk]   waypoint added
> 

Versions: 1.8 – 26.2
Size: 9 – 18 MB
Platforms: Windows / macOS / Linux
Mode: offline

Download

Pick a version and a build, then use the button. Sources are probed before the download starts and the first one that answers is used.

v2.1.0 — release files

file en.zip size — sha256 —

path releases/

Every build is self-contained. Windows, macOS and Linux all ship as PyInstaller single-file binaries, so no Python installation is needed.

The full .zip contains the binary, the matching config file and the readme — that is the recommended first download.

macOS: if Gatekeeper blocks the unsigned binary, right-click it and choose Open, or run xattr -d com.apple.quarantine MinecraftBotClient-en. The published macOS build is Apple silicon (arm64); builds match the architecture of the Python used to produce them. Linux: run chmod +x MinecraftBotClient-en once before launching.

Keep the config beside the binary. config.en.json must sit in the same folder as the client, otherwise the built-in defaults are used.

Sources

Each source is probed with a HEAD request and a 4.5 second timeout. Nothing is uploaded.

Download and extract

Grab the full package for your build and unpack it anywhere. No installer is involved.

Edit the config

Set server_address and minecraft_version. Leave username empty for a random name.

Run the client

Double-click the exe on Windows, or launch ./MinecraftBotClient-en on macOS and Linux. Once the login succeeds you get an interactive console.

Windows 10 / 11Self-contained 64-bit single-file executable.

macOS / LinuxSelf-contained single-file binaries, built natively on each OS.

Python 3.8+Only needed when running main.py from source.

Network accessFor the version check and announcement fetch. Skip with fast_start.

Antivirus false positives

PyInstaller single-file executables unpack themselves at runtime and are frequently flagged heuristically. Whitelist the folder, or run from source with python main.py.

On macOS the same applies to Gatekeeper: right-click the binary and choose Open, or run xattr -d com.apple.quarantine ./MinecraftBotClient-en.

Features

Implemented in the client itself. No mods, no game assets, no launcher.

Version support: Auto-detects the server protocol for any version between 1.8 and 26.2. Unlisted versions inside a range map to the nearest known protocol ID.
SRV records: Resolves _minecraft._tcp.<domain> automatically, so a bare domain works without specifying a port.
Bilingual UI: Chinese or English, selected from the executable suffix: -zh or -en.
Autocomplete: Vanilla-style grey inline preview on . or /. Tab completes and cycles, arrow keys and the mouse wheel browse suggestions.
Chat and commands: Plain text is sent as chat, a leading / sends a server command, a leading . runs a client command that never reaches the server.
Client commands: Ten command families covering connection, logging, spam, walking, eating and live config edits. The legacy // prefix still works.
Human-like actions: Head turns and arm swings follow Bézier trajectories with randomised delays, mimicking real mouse movement.
Multi-bot mode: Launch 20, 100 or more bots from the config with unique random usernames, staggered joins and automatic /register or /login after each bot connects. Broadcast chat to the whole group with .say.
Auto-walk: Random roaming or custom waypoints. Movement stops automatically on damage or death.
Auto-eat: Attempts to eat whenever health falls below a configurable threshold. Toggled at runtime with .eat on and .eat off.
Proximity alerts: Reports nearby players and missing blocks ahead. Printed locally, invisible to other players.
Auto-spam: Configurable rate and message list, persisted to the config file so it survives restarts.
Session logging: Writes a timestamped .log file into log/ for every session while logging is enabled.
Remote checks: Displays remote version and announcement text verbatim on startup. Skip both with fast_start.
Offline mode: Designed for online-mode=false servers. Premium account support is still in development.
Cross-platform: Windows, macOS and Linux, distributed as a native single-file binary built with PyInstaller on each OS. Autocomplete, history and mouse-wheel input work on the Windows console and on POSIX terminals alike.

Quick start

Use a release build, run from source, or produce your own executable.

folder layout

# after extracting releases/2.1.0/windows/en.zip (or macos/, linux/)
MBC/
  MinecraftBotClient-en.exe   # Windows
  MinecraftBotClient-en       # macOS / Linux
  config.en.json
  README.en.md

# edit config.en.json
{
  "username": "",                      // empty = random name
  "server_address": "mc.example.com",  // SRV domains need no port
  "minecraft_version": "1.20.6"
}

# Windows: double-click MinecraftBotClient-en.exe
# macOS / Linux:
chmod +x MinecraftBotClient-en
./MinecraftBotClient-en

bash

# clone
git clone https://github.com/creaddinscart/MinecraftBotClient.git
cd MinecraftBotClient

# dependencies (Windows, macOS and Linux, Python 3.8+)
pip install -r requirements.txt

# run
python main.py

# requests      version check and announcements
# cryptography  AES / RSA for online-mode login (unused offline)
# dnspython     SRV record resolution

bash

# packaging dependency
pip install pyinstaller

# build both language editions for the OS you are on
python build.py

# output (run the script once on each OS you ship)
releases/
  2.1.0/
    windows/  en/ MinecraftBotClient-en.exe  config.en.json  README.en.md
              zh/ MinecraftBotClient-zh.exe  config.zh.json  README.zh.md
              en.zip  zh.zip
    macos/    en/ MinecraftBotClient-en  config.en.json  README.en.md
              ...
    linux/    en/ MinecraftBotClient-en  config.en.json  README.en.md
              ...

Configuration

Edit the values and the JSON updates as you type. Download it, or copy it into the config file next to the executable.

Key	Type	Description
`username`	string	Player name. Empty generates a random one.
`server_address`	string	Server address. SRV domains are supported, or write host:port.
`minecraft_version`	string	Server version, anything between 1.8 and 26.2.
`language`	string	UI language, `zh` or `en`.
`fast_start`	boolean	Skip the version and announcement checks on startup.
`log_enabled`	boolean	Enable session logging by default.
`spam_enabled`, `spam_rate`, `spam_messages`	bool, float, array	Auto-spam switch, rate in messages per second, and the message list.
`command_autocomplete`	boolean	Toggle the grey inline command preview.
`auto_eat`, `auto_eat_health_threshold`	bool, int	Auto-eat switch and the health value that triggers it.
`auto_walk`, `auto_walk_waypoints`	bool, array	Auto-walk switch and custom waypoints in relative coordinates.
`stop_walk_on_damage`	boolean	Stop walking automatically when damaged or killed.
`proximity_alerts`, `proximity_distance`	bool, float	Nearby-player alerts and the radius in blocks.
`human_actions`, `human_action_interval_min`, `human_action_interval_max`	bool, float, float	Human-like actions and the random interval bounds in seconds.
`multi_bot_enabled`, `bot_count`	bool, int	Multi-bot mode and how many bots to launch (e.g. 20 or 100).
`bot_name_prefix`, `bot_name_digits`	string, int	Random username prefix and number of random digits appended.
`bot_join_delay`	float	Seconds between bot connections.
`bot_auth_enabled`, `bot_auth_mode`	bool, string	Auto-login switch and mode: `register`, `login` or `both`.
`bot_auth_password`	string	Password used in the auth commands.
`bot_auth_delay`	float	Seconds after joining before the auth command is sent.
`bot_auth_register_command`, `bot_auth_login_command`	string	Command templates; `{password}` is replaced with `bot_auth_password`.

Commands

A leading . runs a client command that is never sent to the server, a leading / sends a server command, anything else goes out as chat.

Command	Description

Autocomplete keys

Key	Action
`.` or `/`	Show the grey inline preview.
`Tab`	Accept the preview, press again to cycle suggestions.
`↑` / `↓`	Cycle suggestions. Up also browses command history.
Mouse wheel	Cycle suggestions.
`Enter`	Send the input.
`Esc`	Clear the input.

Protocol support

Highest protocol ID per version range. The client probes the server for its real protocol before login, so an exact version is not required.

Version range	Examples	Protocol ID	Mapping

Version lookup

Enter a version to see which range it falls into.

Versions

Every published build lives under releases/<version>/<platform>/. These buttons use the same source probing as the download panel.

Version	Status	Files
2.1.0	latest	`windows/en.zip` `macos/en.zip` (arm64) `linux/en.zip` `MinecraftBotClient-en.exe` `MinecraftBotClient-en` `config` + `README` inside every package
2.0.0	archived	`windows/en.zip` `macos/en.zip` `linux/en.zip` `MinecraftBotClient-en.exe` `MinecraftBotClient-en` `config` + `README` inside every package
1.3.1	archived	`zh.zip` `en.zip` `MinecraftBotClient-zh.exe` `MinecraftBotClient-en.exe`
1.0.3	archived	`MinecraftBotClient-en.exe` `MinecraftBotClient-zh.exe`
1.0.2	archived	`MinecraftBotClient-en.exe` `MinecraftBotClient-zh.exe`

Build layout

From v2.0.0 each platform lives under releases/<version>/<platform>/ with zh/ and en/ folders plus ready-made .zip packages. Older releases keep the original Windows-only layout. Chinese editions of v2.1.0 are available from the download panel above.

FAQ

Can I join a premium (online-mode) server?

No. The client runs in offline mode and targets servers with online-mode=false. A premium server rejects the login with an auth failure, which is expected behaviour.

Premium account support is still in development.

Does it run on macOS and Linux?

Yes. Since v2.0.0 the client ships native single-file builds for Windows, macOS and Linux. Interactive input — autocomplete, history, arrow keys and the mouse wheel — is implemented for both the Windows console API and POSIX terminals, so the console behaves the same on every platform.

On macOS and Linux make the binary executable once with chmod +x MinecraftBotClient-en, then run ./MinecraftBotClient-en. Builds are produced per platform by running python build.py on each OS, because PyInstaller cannot cross-compile.

My antivirus flags the executable

PyInstaller single-file executables unpack themselves at runtime, which heuristic scanners commonly flag. This is a false positive.

Either whitelist the folder or run the project from source with python main.py.

On macOS, Gatekeeper blocks unsigned binaries the same way. Right-click the file and choose Open, or run xattr -d com.apple.quarantine ./MinecraftBotClient-en.

Can I run many bots at once?

Yes. Set multi_bot_enabled to true and choose a bot_count — 20, 100 or more. Each bot gets its own random username and connection, joining with a configurable delay between them.

With bot_auth_enabled on, every bot automatically sends your /register or /login command after joining, so it works on AuthMe-style servers. The console then controls the group: .status, .say <text> and .exit.

Do I need to install Minecraft?

No. MBC speaks the Minecraft protocol directly and ships without game assets — no client jar, no textures, no launcher. That is why the whole client fits in a single 17 MB file.

How do I change the server without editing JSON?

Use the client commands. .esc leaves the current server while keeping the client open, and .connect reconnects with the current config.

To retarget, run .config server_address mc.example.com and then .connect.

Where are the log files?

In a log/ folder beside the executable. Each session creates a new timestamped file such as MBC-2026-09-04_22-55-29.log while logging is enabled.

How do I know my server version is supported?

Anything from 1.8 to 26.2 works. Type the version into the lookup box in the protocol section, or just set minecraft_version in the config — the client probes the server for its real protocol before login.

Startup failed. What should I check?

In order: is the config file in the same folder as the executable, is server_address reachable with the right port, does the server allow offline-mode clients, and is a restricted network blocking the version check?

For the last one, set fast_start to true. The client prints a full traceback, and the same text is written to the session log when logging is enabled.

Is this allowed on public servers?

That depends on the server. Many ban automated clients outright. MBC is published for testing and development — check the rules before using it anywhere.

Disclaimer

Provided for testing and development purposes only. You are responsible for complying with the rules of any server you connect to and with the laws of your jurisdiction. The authors accept no liability for misuse or its consequences.

Minecraft Bot Client

Download

v2.1.0 — release files

Sources

Download and extract

Edit the config

Run the client

Features

Quick start

Configuration

Connection

Behaviour

Logging and spam

Multi-bot

Commands

Autocomplete keys

Protocol support

Version lookup

Versions

FAQ

Minecraft Bot Client

Download

v2.1.0 — release files

Sources re-test

Download and extract

Edit the config

Run the client

Features

Quick start

Configuration

Connection

Behaviour

Logging and spam

Multi-bot

Commands

Autocomplete keys

Protocol support

Version lookup

Versions

FAQ

Sources