Crafty Discord Bot

A Discord slash-command bot for querying and controlling Minecraft servers managed by Crafty Controller on GitLab.

This bot supports multiple servers, role-based permissions, and runs cleanly in Docker.

This project is not affiliated with the Crafty Controller team; it simply uses their public API.

This is a personal project shared publicly. I may not respond to issues or feature requests.

---

Features

• /mc slash command with action choices:
  • Status
  • Start
  • Stop
  • Restart
• Supports multiple Minecraft servers
• Optionally restricts which Discord roles can control servers
• Works in a single Discord channel or globally
• Compatible with reverse proxies and containerized environments
• Optional HTTP health endpoint for container orchestration

---

Requirements

• Discord Bot Token
• Discord bot permissions / scopes
  • OAuth2 scopes: bot, applications.commands
  • No privileged intents are required for basic slash-command usage
• Crafty Controller API Token
• Crafty Controller URL
• Python 3.11+ and uv (recommended for local runs) or Docker

Crafty must have API access enabled.

---

Installation

Docker Compose

Step 1 — Download the required files

Create a folder and go into it:

mkdir mc-discord-bot && cd mc-discord-bot

Download the Docker Compose file:

wget -O docker-compose.yml https://raw.githubusercontent.com/owlburtoe/mc-discord-bot/main/docker-compose.yml

and the environment template:

wget -O .env https://raw.githubusercontent.com/owlburtoe/mc-discord-bot/main/example.env

Step 2 — Configure

Open .env in your editor and populate it with your values:

• PUID/PGID (REQUIRED for Crafty to run properly!!)
• Discord bot token
• Crafty URL and token

Download the servers template:

wget -O servers.json https://raw.githubusercontent.com/owlburtoe/mc-discord-bot/main/servers.json.example

Open servers.json in your editor and define your servers.

Step 3 — Start the bot

The docker-compose.yml file is configured to automatically download the latest secure build directly from the GitHub Container Registry (ghcr.io).

Bring it online:

docker compose up -d

Note: If you are making modifications and prefer to build the bot locally from source rather than pulling the pre-built image, you can use docker-compose-build.yml instead.

The bot won't fully start until all the required variables in .env are entered. Crafty will begin to run as long as PUID/PGID and TZ are provided.

To view logs:

docker compose logs -f

Step 4 - Visit Crafty4

• Visit https://localhost:8443 to access the Controller and start your first server!

• Visit Crafty Controller on GitLab for instructions on starting your first server!

Development

This project uses ruff for lightning-fast linting and formatting.

🧹 Linting

To check for issues and automatically fix what's possible:

uv run ruff check --fix .

✨ Formatting

To format the codebase:

uv run ruff format .

License

• You do not edit the container image
• You update configuration only through .env
• Recreate the container when .env changes

Configuration

The bot is configured entirely through environment variables.

See example.env for a complete template.

Discord configuration

Variable	Description
DISCORD_TOKEN	Bot token from Discord Developer Portal
GUILD_ID	Optional: Restrict slash commands to one guild
ALLOWED_CHANNEL_ID	Optional: Channel ID where commands are allowed/wanted
OWNER_ID	Discord user ID with FULL permissions
MOD_ROLE_ID	Role allowed control actions

Crafty Controller configuration

Variable	Description
CRAFTY_URL	Base URL of your Crafty Controller
CRAFTY_TOKEN	API token made in Crafty

Defining Minecraft servers

The recommended way to define servers is using a servers.json file.

servers.json format:

[
  {
    "key": "surv",
    "name": "Survival",
    "id": "00000000-0000-0000-0000-000000000001"
  },
  {
    "key": "crea",
    "name": "Creative",
    "id": "00000000-0000-0000-0000-000000000002"
  }
]

Copy servers.json.example to servers.json and edit.

Alternate: Environment Variable

You can also provide server definitions as a JSON string in the MC_SERVERS_JSON environment variable.

Legacy Method (Deprecated)

Servers can be mapped by index using the following pattern: MC_SERVER_<N>_KEY, MC_SERVER_<N>_NAME, MC_SERVER_<N>_ID.

Example: MC_SERVER_1_KEY=surv MC_SERVER_1_NAME=Survival MC_SERVER_1_ID=00000000-0000-0000-0000-000000000001

Slash Command Usage

In Discord: /mc

Actions:

• 📊 Status
• ▶️ Start
• ⏹️ Stop
• 🔁 Restart

Server names match the values defined in your environment file.

Health Check Endpoint (optional)

GET /health

Response example:

{
  "status": "ok",
  "servers": 3
}

Enable by exposing port 8085 in Docker if needed by your orchestrator.

---

Common Issues

Commands not showing up

• Ensure the bot has application.commands scope
• If using GUILD_ID, the guild must match your server
• Wait a few minutes for global command propagation

“Unknown server”

• Key/name mismatch between .env and command
• Incorrect server UUID

401 / Crafty API failure

• API token invalid
• Crafty URL incorrect
• HTTPS certificate issues if using self-signed certs