https://github.com/kieranmcm07/discord_moderation_bot
Feature-rich Discord moderation bot with tickets, AutoMod, appeals, activity tracking, music, and staff dashboards.
https://github.com/kieranmcm07/discord_moderation_bot
appeals automod discord-bot discord-py moderation-bot python sqlite tickets
Last synced: 8 days ago
JSON representation
Feature-rich Discord moderation bot with tickets, AutoMod, appeals, activity tracking, music, and staff dashboards.
- Host: GitHub
- URL: https://github.com/kieranmcm07/discord_moderation_bot
- Owner: Kieranmcm07
- License: mit
- Created: 2026-04-11T19:10:05.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-11T15:25:05.000Z (13 days ago)
- Last Synced: 2026-06-11T16:22:13.784Z (12 days ago)
- Topics: appeals, automod, discord-bot, discord-py, moderation-bot, python, sqlite, tickets
- Language: Python
- Homepage:
- Size: 1.28 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Discord Moderation Bot
A polished discord.py staff toolkit for keeping Discord communities cleaner,
calmer, and easier to run.
Moderation, tickets, activity tracking, AutoMod, Sentinel, setup checks, and music tools
all live inside Discord.
Workflow
|
Features
|
Screenshots
|
Setup
|
Commands
|
Configuration
Built for busy staff teams:
diagnose setup issues, handle incidents, open tickets, review cases, watch risk signals,
and keep community extras in one bot without a separate web dashboard.
> Tip: after inviting the bot, run `,doctor` in a server channel to check
> permissions, logging channels, and setup gaps before staff start using it.
## Staff Workflow
1. Check The Setup
Run ,doctor to catch missing permissions, channel gaps, and setup issues
before staff need the bot under pressure.
2. Work From Mission Control
Use ,missioncontrol for server health, open tickets, moderation load,
activity signals, and suggested next actions.
3. Respond With Context
Pull ,member360, case history, Sentinel signals, chat logs, and tickets
into the same staff workflow.
## At A Glance
Command Center
Mission Control, Bot Doctor, setup checks, server health, and staff prompts.
Case Engine
Warnings, bans, timeouts, notes, chat logs, escalation rules, and CSV exports.
Safety Automation
AutoMod, Sentinel risk signals, invite logging, autoroles, and sticky messages.
Community Layer
Tickets, appeals, reminders, AFK, reaction roles, custom commands, and music.
## Features
Complete moderation workflow
Ban, tempban, softban, kick, warn, timeout, clean messages, slowmode, add private notes,
export chat logs, and configure automatic warning escalations.
Case history that staff can actually use
Search cases, edit reasons, add follow-up comments, view recent actions, build compact
moderator summaries, and export case files as CSV.
Mission Control dashboard
See server health, moderation load, open tickets, activity, Sentinel status, and suggested
staff actions from inside Discord.
Member 360 profiles
Combine account age, moderation history, chat activity, voice time, and live Sentinel risk
signals into one staff-friendly view.
Tickets and appeals
Build ticket panels with category buttons, private channels, staff roles, transcripts,
logs, user controls, renaming, and moderation appeal decisions.
AutoMod and Sentinel
Block terms, delete invites and links, detect mass mentions, spot spam, link floods,
suspicious join waves, and new-account risk.
Server management tools
Welcome and leave messages, invite logs, deleted and edited message audits, polls,
announcements, locks, nicknames, autoroles, and branded embeds.
Community extras
Activity leaderboards, reminders, AFK statuses, reaction-role buttons, custom commands,
fun commands, and music playback with queues and filters.
## Screenshots
These screenshots live in `docs/screenshots/`, so they render directly on the
GitHub project page.
Mission Control
Bot Doctor
Ticket Panel
Member 360
Sentinel Threat Radar
## Requirements
- Python 3.10 or newer
- A Discord bot application and token
- Discord privileged intents enabled for:
- Server Members Intent
- Message Content Intent
- FFmpeg on your system path if you want to use the music commands
- Optional Spotify developer app credentials if you want `,play` to accept
Spotify track, album, and playlist links
Recommended Discord permissions:
- View Channels
- Send Messages
- Embed Links
- Read Message History
- Manage Messages
- Manage Channels
- Manage Roles
- Manage Nicknames
- Kick Members
- Ban Members
- Moderate Members
- Manage Guild
- View Audit Log
## Setup
1. Clone the repository.
```bash
git clone https://github.com/Kieranmcm07/Discord_Moderation_Bot.git
cd Discord_Moderation_Bot
```
2. Install dependencies.
```bash
pip install -r requirements.txt
```
3. Create your environment file.
```bat
copy .env.example .env
```
4. Fill in `.env`.
```env
BOT_TOKEN=YOUR_BOT_TOKEN_HERE
PREFIX=,
OWNER_IDS=
MOD_LOG_CHANNEL_ID=0
INVITE_LOG_CHANNEL_ID=0
JOIN_LOG_CHANNEL_ID=0
DB_PATH=data/bot.db
SPOTIFY_CLIENT_ID=
SPOTIFY_CLIENT_SECRET=
SPOTIFY_MAX_TRACKS=50
SPOTIFY_MARKET=US
BOT_FAILURE_MODE=retry
BOT_RETRY_DELAY_SECONDS=5
```
Only `BOT_TOKEN` is required. Spotify values are only needed for Spotify music
links. The other values can be left as defaults or configured later with bot
commands.
5. Run the bot.
```bash
py -3 main.py
```
If the Python launcher is not available on your machine, use your normal Python
command instead:
```bash
python main.py
```
### Optional Spotify Music Links
To use Spotify URLs with `,play`, create a Spotify app in the Spotify Developer
Dashboard and copy its Client ID and Client Secret into `.env`:
```env
SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_MAX_TRACKS=50
SPOTIFY_MARKET=US
```
Supported inputs:
- `https://open.spotify.com/track/...`
- `https://open.spotify.com/album/...`
- `https://open.spotify.com/playlist/...`
- `spotify:track:...`, `spotify:album:...`, and `spotify:playlist:...`
Spotify is used for metadata only. The bot reads the Spotify title/artist list,
then searches for a playable audio match through the existing `yt-dlp` music
flow. `SPOTIFY_MAX_TRACKS` caps album and playlist expansion between 1 and 100
tracks so a very large playlist does not lock up the music command.
`SPOTIFY_MARKET` controls the country used for Spotify availability checks;
use `GB` instead of `US` if you want UK availability.
## Windows Helper Scripts
The repository includes Windows batch files for common local workflows:
| Script | Purpose |
| --- | --- |
| `start_bot.bat` | Start the bot through the launcher |
| `restart_bot.bat` | Restart the bot |
| `stop_bot.bat` | Stop the running bot process |
| `install_startup.bat` | Add the bot to Windows startup |
| `remove_startup.bat` | Remove the Windows startup entry |
When failure handling is set to `retry`, unexpected top-level crashes are
retried after 5 seconds by default. During launcher startup retries, press `C`
to close instead.
## Configuration
Environment values are loaded from `.env`.
| Variable | Description |
| --- | --- |
| `BOT_TOKEN` | Discord bot token |
| `PREFIX` | Text command prefix, default `,` |
| `OWNER_IDS` | Comma-separated Discord user IDs treated as bot owners |
| `DB_PATH` | SQLite database path, default `data/bot.db` |
| `BOT_FAILURE_MODE` | `retry` to restart after unexpected failures, or `close` to exit |
| `BOT_RETRY_DELAY_SECONDS` | Seconds to wait before retrying, default `5` |
| `MOD_LOG_CHANNEL_ID` | Optional fallback moderation log channel |
| `INVITE_LOG_CHANNEL_ID` | Optional invite log channel |
| `JOIN_LOG_CHANNEL_ID` | Optional join and leave log channel |
Most server-specific setup can be managed inside Discord:
```text
,settings
,setmodlog #channel
,setmessagelog #channel
,setwelcomechannel #channel
,setwelcomemessage
,setleavechannel #channel
,setleavemessage
,setembedcolor
,setembedimage
```
Welcome and leave templates support `{user}`, `{username}`, `{server}`, and
`{count}` placeholders. Custom command responses support `{user}`, `{username}`,
and `{server}`.
## Command Overview
The default prefix in this README is `,`. Change it with `PREFIX` in `.env`.
### Command Center
| Command | Description |
| --- | --- |
| `,missioncontrol` | Open the staff operations dashboard |
| `,dashboard` | Alias for Mission Control |
| `,doctor` | Diagnose permissions and setup gaps |
| `,member360 @user` | Show a complete staff profile for one member |
### Moderation
| Command | Description |
| --- | --- |
| `,ban @user [reason]` | Ban a member |
| `,tempban @user [reason]` | Ban a member for a limited time |
| `,tempbans` | Show active temporary bans |
| `,unban [reason]` | Unban a user by ID |
| `,kick @user [reason]` | Kick a member |
| `,softban @user [days] [reason]` | Ban then unban a member to clear recent messages |
| `,warn @user [reason]` | Warn a member |
| `,warnings @user` | Show active warnings |
| `,clearwarns @user [amount] [reason]` | Remove recent warnings |
| `,note @user ` | Add a private moderator note |
| `,timeout @user [duration] [reason]` | Timeout a member |
| `,untimeout @user [reason]` | Remove a timeout |
| `,purge ` | Delete recent messages |
| `,clean [@user]` | Delete recent messages, optionally from one user |
| `,chatlog [#channel] [amount]` | Export recent messages as a text file |
| `,purgelinks ` | Delete recent messages containing links |
| `,purgebots ` | Delete recent bot messages |
| `,slowmode [seconds]` | Set channel slowmode |
| `,setescalation [duration]` | Configure automatic warning punishments |
| `,removeescalation ` | Remove an escalation rule |
| `,escalations` | List escalation rules |
### Cases
| Command | Description |
| --- | --- |
| `,case ` | Look up one case |
| `,history @user` | Show a user's moderation history |
| `,modsummary @user` | Show a compact moderation summary |
| `,casefile @user [limit]` | Export moderation history as CSV |
| `,recentcases [limit]` | Show recent moderation actions |
| `,searchcases ` | Search cases by action or reason |
| `,casecomment ` | Add a follow-up note |
| `,reason ` | Update a case reason |
### Tickets And Appeals
| Command | Description |
| --- | --- |
| `,setticketcategory ` | Set the ticket channel category |
| `,setticketlog #channel` | Set the ticket log channel |
| `,ticketroleadd ` | Allow a role to access tickets |
| `,ticketroleremove ` | Remove a ticket staff role |
| `,ticketroles` | Show ticket staff roles |
| `,ticketcategoryadd Name \| Emoji \| Description` | Add a ticket type |
| `,ticketcategoryremove ` | Remove a ticket type |
| `,ticketcategories` | List ticket types |
| `,ticketpanel [#channel]` | Post the ticket panel |
| `,ticketsettings` | Show ticket settings |
| `,ticketadd @user` | Add a user to the ticket |
| `,ticketremove @user` | Remove a user from the ticket |
| `,ticketrename ` | Rename the current ticket channel |
| `,closeticket` | Close the current ticket |
| `,appealpanel [#channel]` | Post the case appeal panel |
| `,appeal accept ` | Accept the current appeal |
| `,appeal deny ` | Deny the current appeal |
| `,appeal close` | Close the current appeal ticket |
### AutoMod And Sentinel
| Command | Description |
| --- | --- |
| `,automod` | Show AutoMod settings |
| `,automod on/off` | Enable or disable AutoMod |
| `,automod invites on/off` | Delete Discord invite links |
| `,automod links on/off` | Delete external links |
| `,automod mentions ` | Set the mass mention threshold |
| `,automod warn on/off` | Add warning cases when AutoMod deletes |
| `,automod addword ` | Add a blocked word or phrase |
| `,automod removeword ` | Remove a blocked word or phrase |
| `,automod words` | List blocked terms |
| `,sentinel` | Show the live threat radar panel |
| `,sentinel on/off` | Enable or disable Sentinel |
| `,sentinel threshold <40-95>` | Set the alert risk score |
| `,sentinel log #channel` | Set the Sentinel alert channel |
| `,sentinel autotimeout ` | Auto-timeout high-risk users |
| `,sentinelprofile @user` | Show a member's live behaviour profile |
| `,sentinelincidents [limit]` | Show recent Sentinel incidents |
### Server Management
| Command | Description |
| --- | --- |
| `,serverinfo` | Show server details |
| `,userinfo [@user]` | Show user details |
| `,avatar [@user]` | Show a user's avatar |
| `,roleinfo ` | Show role details |
| `,announce #channel ` | Send an announcement embed |
| `,poll Question \| Option 1 \| Option 2` | Create a reaction poll |
| `,lock [#channel] [reason]` | Lock a channel |
| `,unlock [#channel] [reason]` | Unlock a channel |
| `,nick @user ` | Change a member's nickname |
| `,resetnick @user` | Reset a nickname |
| `,setautorole ` | Set the automatic join role |
| `,autorole` | View the current autorole |
| `,clearautorole` | Disable autorole |
| `,setsticky [#channel] ` | Set a sticky message |
| `,sticky [#channel]` | View a sticky message |
| `,stickies` | List sticky messages |
| `,clearsticky [#channel]` | Remove a sticky message |
| `,botinfo` | Show bot stats |
### Configuration
| Command | Description |
| --- | --- |
| `,settings` | Show server configuration |
| `,setwelcomechannel #channel` | Set the welcome channel |
| `,setwelcomemessage ` | Set the welcome template |
| `,setleavechannel #channel` | Set the leave channel |
| `,setleavemessage ` | Set the leave template |
| `,setembedcolor ` | Set the default embed color |
| `,setembedimage ` | Set a shared embed image or GIF |
| `,clearembedimage` | Remove the shared embed image |
| `,setmodlog #channel` | Set moderation action logs |
| `,viewmodlog` | Show the moderation log channel |
| `,clearmodlog` | Disable moderation action logs |
| `,setmessagelog #channel` | Set deleted and edited message audit logs |
| `,viewmessagelog` | Show the message audit log channel |
| `,clearmessagelog` | Disable message audit logs |
### Community Tools
| Command | Description |
| --- | --- |
| `,topchat [limit]` | Show top message senders |
| `,topvoice [limit]` | Show top voice users |
| `,stats [@user]` | Show activity stats |
| `,rradd @role [Label \| Emoji]` | Add or update a reaction-role option |
| `,rrremove @role` | Remove a reaction-role option |
| `,rrlist` | List reaction roles |
| `,rrpanel [#channel]` | Post the role button panel |
| `,remind
### Music
| Command | Description |
| --- | --- |
| `,join` | Join your current voice channel |
| `,play ` | Play audio from a URL, search term, Spotify track, Spotify album, or Spotify playlist |
| `,queue` | Show the queue |
| `,controls` | Show interactive music controls |
| `,skip` | Skip the current track |
| `,pause` | Pause playback |
| `,resume` | Resume playback |
| `,loop [on/off]` | Repeat the current track |
| `,shuffle` | Shuffle queued tracks |
| `,remove ` | Remove a queued track |
| `,move ` | Move a queued track |
| `,jump ` | Skip ahead to a queued track |
| `,replay` | Restart the current track |
| `,volume [0-200]` | Show or set playback volume |
| `,filters` | List available audio filters |
| `,filter ` | Apply an audio filter |
| `,bassboost` | Turn on bass boost |
| `,chipmunk` | Turn on the chipmunk filter |
| `,stop` | Stop playback and clear the queue |
| `,leave` | Leave the current voice channel |
| `,nowplaying` | Show the current track |
### Fun And Utility
| Command | Description |
| --- | --- |
| `,help [command]` | Show grouped help or details for one command |
| `,help search ` | Search commands |
| `,ping` | Check websocket latency |
| `,about` | Show project and creator links |
| `,8ball ` | Ask the magic 8-ball a question |
| `,coinflip` | Flip a coin |
| `,roll [max]` | Roll a number |
| `,choose Option 1 \| Option 2` | Choose between options |
| `,joke` | Tell a clean joke |
| `,meme [top \| bottom]` | Post a generated meme image |
| `,ship @user1 @user2` | Generate a fun ship score |
## Data And Behaviour Notes
- The bot stores local data in SQLite, by default at `data/bot.db`.
- Temporary bans are checked and lifted in the background while the bot is
online.
- Reminders are stored in SQLite and still deliver after restarts once due.
- Durations support compact and readable formats such as `30m`, `1h30m`,
`2 hours`, and `7d`.
- Sentinel stores incident metadata, not full message content.
- Voice activity tracking only records time while the bot is running.
- Guilds can set a custom embed color and an optional shared image or GIF for
branded embeds.
- Once the bot is fully offline, Discord cannot deliver commands to it, so it
cannot reply until it starts again.
## Project Structure
```text
.
|-- cogs/
| |-- activity.py
| |-- afk.py
| |-- appeals.py
| |-- automod.py
| |-- cases.py
| |-- command_center.py
| |-- configuration.py
| |-- custom_commands.py
| |-- fun.py
| |-- help.py
| |-- invite_logger.py
| |-- message_audit.py
| |-- moderation.py
| |-- music.py
| |-- reaction_roles.py
| |-- reminders.py
| |-- server_management.py
| |-- sentinel.py
| |-- tickets.py
| `-- utility.py
|-- data/
|-- docs/
| |-- assets/
| | |-- readme-banner.svg
| | `-- readme-moderation-loop.gif
| `-- screenshots/
|-- tests/
|-- utils/
| |-- db.py
| |-- embeds.py
| |-- errors.py
| `-- time.py
|-- .env.example
|-- config.py
|-- launcher.py
|-- main.py
`-- requirements.txt
```
## License
This project is licensed under the MIT License.