A multi-purpose Discord bot built with discord.py and a MySQL/MariaDB backend, covering server moderation, a global cross-server blacklist network, tickets, giveaways, applications, automod, a starboard, and per-server bot personalization.
Note on how this was built: This bot has been made with Claude Code Sonnet 4.6 due to the price of this software being 7€ for the recipient.
This has been made by ghulq.
- Features
- Tech stack
- Project structure
- Setup
- Configuration (
.env) - Database schema
- Running the bot
- Command overview
- License
- RE-staff-only global blacklist of users and servers, enforced across every server the bot is in.
/blacklist adduser/removeuser/addserver/removeserver— manage the global lists./blacklist view— view all blacklisted users/servers with optional search by ID or reason text./report user//report server— any member can report a user or server for RE staff review./reports list/accept/reject— RE staff review queue for incoming reports.- Automatic enforcement: blacklisted users are banned on join, blacklisted servers' invite links are deleted on post.
/whitelist add/remove/list— per-server exemptions from blacklist enforcement./protection toggle— per-server opt-in/out of user/server blacklist enforcement (Manage Server)./protection check— public, anyone can check whether a server has blacklist enforcement enabled.
/staffroles— pick which roles count as "staff" on a server via a role-select menu.- Members with a configured staff role (or Manage Server) can use staff-gated commands across tickets, applications, and giveaways — without needing full server admin permissions.
/ticketpanel create— build a ticket panel (title, description, color, button label, category, support role, custom welcome message) via a modal./ticket config— edit an existing panel's text, color, button label, welcome message, category, or support role through buttons/modals/selects.- Members open tickets with one click; the bot creates a private channel with the opener and support role.
- Claim system: staff can claim/unclaim a ticket via a button or
/ticket claim. Clicking again as the same claimer unclaims it; other staff get a "already claimed" notice instead of stealing it. - Customizable welcome message per panel, shown in every ticket opened from it (falls back to a sensible default).
Close Ticketbutton closes and deletes the channel after a short grace period.
/giveaway start— prize, duration, winner count, required role, accent color, image/thumbnail (as file uploads), and up to 3 bonus-entry roles.- Giveaway ID is shown directly on the giveaway message.
- Bonus entries: configure roles that grant extra entries (e.g. boosters get +2); winners are drawn from a weighted pool.
- Templates:
/giveaway template save/list/delete— save reusable defaults (prize, winners, role, color, image, thumbnail) and load them withtemplate:on/giveaway start. /giveaway end,/giveaway reroll,/giveaway info— manage and inspect giveaways by ID.
/application create— build an application form with up to 5 questions, a review channel, and an optional auto-granted role on acceptance./application panel— post a persistent Apply Now button so members can apply without typing any command./apply— members can also apply by typing the command directly.- Reviewers accept/deny from buttons on the submission; the applicant is DM'd the result and granted the role automatically if accepted.
/application list/toggle/delete— manage forms (staff-gated).
/personalize name— free per-server nickname change./personalize avatar/banner/bio— Bot+ features: per-server bot avatar, banner, and bio.- Bot+ access is granted either per-server by RE staff (
/botplus grant/revoke), or automatically to any user holding the configuredPREMIUM_ROLEin the RE guild.
/automod toggle/defaultlist/status— enable/disable the word filter and the built-in slur list./automod word add/remove/list— per-server custom blacklisted words.- Matches are deleted automatically and logged to the configured log channel.
/warn,/kick,/ban,/unban,/timeout,/untimeout,/purge— standard moderation actions with role-hierarchy checks./cases— view a member's moderation history on the server.- Every action is recorded as a case and logged to the configured log channel.
/starboard setup— channel, emoji, and star threshold./starboard disable— turn it off.- Starred messages are mirrored to the starboard channel and kept in sync as reactions change.
/ping— websocket/database latency, CPU/RAM usage, and uptime./logging setchannel/disable— configure where blacklist/automod/moderation events get logged.- Bot presence automatically reflects the current server count.
- Python 3.11+, discord.py 2.7+ (using Components V2 /
LayoutViewfor all bot messages) - MySQL/MariaDB via
asyncmy(async connection pool) python-dotenvfor configuration,psutilfor resource metrics
main.py Bot entrypoint, cog loading, DB connection lifecycle
config.py Environment-driven configuration
schema.sql Full database schema (idempotent CREATE/ALTER statements)
cogs/ Discord-facing commands, buttons, modals, and listeners
core/ Database access layer (one module per feature area)
utils/ Shared helpers: Components V2 view builders, permissions, duration parsing, text filtering
Each feature has a cogs/<feature>.py (Discord layer) paired with a core/<feature>.py (database layer) — keep that separation when extending the bot.
- Install Python 3.11+ and a MySQL or MariaDB server.
- Create a virtual environment and install dependencies:
python -m venv venv venv/Scripts/activate # Windows pip install -r requirements.txt - Copy
.env.exampleto.envand fill in the values (see below). - Apply the database schema (see Database schema).
- Run the bot (see Running the bot).
| Variable | Description |
|---|---|
DISCORD_TOKEN |
Your bot's token from the Discord Developer Portal. |
RE_GUILD_ID |
The ID of the staff/"RE" guild. RE-only commands (global blacklist management, report review, Bot+ grants) only work in this guild. |
PREMIUM_ROLE |
Role ID in RE_GUILD_ID. Any user holding this exact role is treated as having Bot+ personalization access on every server, in addition to per-server grants. |
DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_NAME |
MySQL/MariaDB connection details. |
BRAND_COLOR |
Default accent color (hex int, e.g. 0x5865F2) used across Components V2 messages. |
schema.sql contains the full set of tables, using CREATE TABLE IF NOT EXISTS and ALTER TABLE ... ADD COLUMN IF NOT EXISTS so it can be run repeatedly and safely against an existing database (MySQL 8.0.29+ / MariaDB 10.6+ required for the conditional ALTER TABLE statements). Apply it with any MySQL client, e.g.:
mysql -h <DB_HOST> -P <DB_PORT> -u <DB_USER> -p <DB_NAME> < schema.sqlpython main.pyOn startup the bot connects to the database, loads all cogs listed in main.py, syncs the application command tree, and registers persistent views (ticket panels, open tickets, application panels, active giveaways) so buttons keep working across restarts.
Run / in Discord to browse the full, live command list with descriptions — the summary above covers the major command groups (/blacklist, /report, /reports, /whitelist, /protection, /staffroles, /ticketpanel, /ticket, /giveaway, /application, /apply, /personalize, /botplus, /automod, /warn//kick//ban/etc., /cases, /starboard, /logging, /ping).
This software is not open source in the permissive sense — it is proprietary and fully owned by ghulq. Modifying it requires ghulq's prior written approval, and any approved modification must keep this license attached and be published publicly. See LICENSE for the full terms, including the legal remedies ghulq reserves against unauthorized alterations.