A feature-rich, self-hosted Discord bot with a web dashboard
A fully configurable AI assistant powered by Google Gemini, Claude, or GPT-4o.
- Responds in active channels and to @mentions anywhere
- Personality modes — Manual system prompt, choose a Preset, or Auto-generate from a description
- 5 built-in presets — Friendly Helper, Anime Waifu, Professional Assistant, Caine (TADC), Winston (Overwatch)
- Response length — Short, Medium, or Long
- Behaviour flags — markdown control, emoji toggle, mention on reply, Discord quote-reply, typing indicator
- Webhook persona — custom bot name and avatar per server via Discord webhook
- Long-term memory — remembers things about each user across conversations
- Web search — auto-injects DuckDuckGo results for factual queries
- URL summarisation — reads and summarises linked pages
- Image generation —
/imaginevia fal.ai or Pollinations.ai fallback - Blocklist — refuse to discuss specific topics per server
- Bring your own key — use Claude, GPT-4o, or premium Gemini with your own API key
Full-featured music bot powered by yt-dlp.
- Play from YouTube, Spotify, Tidal, or search queries
- YouTube playlist support — entire playlist queued at once
- Interactive search picker — choose from top results before playing
- Queue management — skip, stop, pause, resume, shuffle, loop
- Audio filters — bass boost, nightcore, vaporwave, and more
- SoundCloud fallback when a stream fails
- Auto-disconnect on inactivity
Keep your server safe with a full moderation suite.
/kick,/ban,/unban,/softban,/timeout,/warn,/warnings,/purge/modlog— queryable history of all mod actions with optional user/moderator filter/delwarn— delete a specific warning by case ID- All actions logged persistently with timestamps
Automatic server defence against raids and spam.
- Mass join detection — triggers lockdown when a flood of accounts joins
- New account filter — block accounts younger than a configurable age
- Mention spam — auto-mute on excessive pings
- Message spam — rate-limit enforcement per user
/antiraid set/show/lockdown/unlockfor manual control
Automatic message translation per channel.
- Translate messages to any language on the fly (no API key required)
- Per-channel configuration via dashboard
Run timed giveaways directly in Discord.
- Create giveaways with a prize, duration, and winner count
- Auto-end and auto-announce winner(s) when time expires
/giveaway rerollto re-pick a winner- Dashboard management
Export and restore all bot configuration for a server.
- Single-command full backup of all settings as JSON
- Restore from backup on any server
Speak text aloud in voice channels using Google TTS.
- Supports multiple languages
- Per-server default language configuration
Play custom sound effects in voice channels.
- Upload and manage
.mp3/.wavfiles per server - Autocomplete from all available sounds
AI-powered audio stem separation.
- Upload any audio file and receive separate vocal and instrumental tracks as
.wavfiles
Automatically announces free games across platforms.
- Monitors Epic Games, Steam, GOG, Ubisoft, Humble Bundle, and more
- Reddit
/r/FreeGameFindingsintegration - Per-server platform filter and optional role mention
Go-live alerts for your favourite streamers.
- Track Twitch streamers per server
- Rich embeds with game, viewer count, and title
Stay on top of active Twitch Drop campaigns.
- Automatic detection of active drops with per-game filtering
Gamify your server with a full XP system.
- Configurable XP rate and cooldown
- Role rewards at level thresholds
- Customisable level-up messages with variable substitution
- Leaderboard support
Build your own commands without code.
- Text, embed, and auto-reply response types
- Trigger on: exact match, contains, regex, links, files, emojis, role mentions
- Per-command cooldowns, role restrictions, and usage statistics
- Fully customisable welcome and goodbye messages with embed support
- Test command to preview before going live
Let members self-assign roles with emoji reactions.
Automatically assign roles when members join.
Track server activity in a dedicated log channel.
- Message edits and deletions, member joins/leaves, role changes
- Ghost ping detection — alerts when a mention is removed via edit or delete
Lighthearted commands for entertainment.
/meme,/joke,/8ball,/coinflip,/roll,/mock,/ship,/rate, and more/ratescores anything 1-100, with server-defined verdict tiers and rigged answers/animal snail🐌 draws from an image pack — 40 bundled images, plus any your server adds
- Right-click any message → Apps → Quote as image, or
/ooc <link> - Renders the message as a themeable card: avatar, name, text, timestamp
- Eight presets — dark, light, midnight, sepia, silly, vaporwave, terminal, newspaper
- Full control of colours, gradients, fonts, text alignment, avatar side/size/shape, text outline, frame border and rounded corners
- Chinese, Japanese, Korean, Hebrew, Arabic and colour emoji all render
- One fact a day, posted at a time and timezone each server picks
- Four mixable sources with per-server weights: 594 bundled facts, public fact APIs, your server's own list, and AI-generated facts on a topic you choose
- Category filters, no-repeat window, optional role ping and discussion thread
/help— categorised, searchable command reference/userinfo,/serverinfo,/ping,/uptime
Manage the entire bot through a clean web interface — no Discord commands required.
| Section | What you can do |
|---|---|
| Servers | Overview of all connected servers |
| AI Chatbot | Personality, behaviour, webhook persona, channels, blocklist, API key |
| Custom Commands | Create, edit, and delete commands |
| Welcome | Configure welcome/goodbye messages and channels |
| Leveling | XP rates, level-up messages, role rewards |
| Reaction Roles | Emoji-to-role mappings |
| Auto Roles | Roles assigned on join |
| Moderation | View mod log, manage warnings |
| Anti-Raid | Configure thresholds and view raid log |
| Giveaways | Create and manage giveaways |
| Backup | Export or restore server configuration |
| Auto-Translate | Per-channel translation settings |
| Free Stuff | Alert channels, platform filters, test notifications |
| Streaming | Add and remove tracked Twitch streamers |
| Twitch Drops | Configure drop alerts and game filters |
| TTS | Default language and toggle |
| Audit Log | Choose events to log and target channel |
- Python 3.12+
- FFmpeg installed and on
PATH - A Discord bot token — create one here
# 1. Clone the repo
git clone https://github.com/FishyShu/Discord-Bot-Python.git
cd Discord-Bot-Python
# 2. Install dependencies
pip install -r requirements.txt
# 3. Configure environment
cp .env.example .env
# Edit .env with your tokens and settings
# 4. Run
python bot.pycp .env.example .env
# Edit .env
docker compose up -d| Variable | Required | Description |
|---|---|---|
DISCORD_TOKEN |
✅ | Your bot token |
DISCORD_CLIENT_ID |
✅ | OAuth2 client ID |
DISCORD_CLIENT_SECRET |
✅ | OAuth2 client secret |
DASHBOARD_SECRET_KEY |
✅ | Secret key for session cookies |
DASHBOARD_PASSWORD |
✅ | Dashboard login password |
DASHBOARD_PORT |
— | Dashboard port (default 5000) |
SPOTIFY_CLIENT_ID |
— | Spotify API client ID (music) |
SPOTIFY_CLIENT_SECRET |
— | Spotify API client secret (music) |
FAL_API_KEY |
— | fal.ai key for image generation (optional, falls back to Pollinations) |
ENCRYPTION_KEY |
— | Fernet key for encrypting user-provided API keys |
SYNC_COMMANDS |
— | Set to 1 to force-sync slash commands on startup |
SYNC_GUILD_ID |
— | Dev only: sync commands to one guild (instant) instead of globally (up to 1h) |
All commands use Discord's native slash command system. Use /help in Discord for the full searchable reference.
| Command | Description |
|---|---|
/ai config personality |
Set personality mode (manual / preset / auto-generate) |
/ai config length |
Set response length (short / medium / long) |
/ai config formatting |
Configure markdown and emoji usage |
/ai config behaviour |
Toggle mentions, reply mode, typing indicator |
/ai config language |
Set the response language |
/ai config webhook-set |
Configure a webhook persona (custom name + avatar) |
/ai config webhook-clear |
Remove the webhook persona |
/ai memory |
View what the bot remembers about you |
/ai memory clear |
Clear your memory for this server |
/ai info |
Show current AI config for this server |
/imagine <prompt> |
Generate an image with AI |
| Command | Description |
|---|---|
/play <query> |
Play a song or add to queue (YouTube / Spotify / Tidal / search) |
/search <query> |
Search YouTube and pick a result |
/skip |
Skip the current track |
/queue |
Show the current queue |
/pause / /resume |
Pause or resume playback |
/stop |
Stop playback and clear the queue |
/nowplaying |
Show the current track |
/loop |
Toggle loop mode |
/shuffle |
Shuffle the queue |
/musicconfig |
Configure music settings (fallback service, etc.) |
| Command | Description |
|---|---|
/kick <member> |
Kick a member |
/ban <member> |
Ban a member |
/unban <user> |
Unban a user |
/softban <member> |
Ban and immediately unban (clears messages) |
/timeout <member> <duration> |
Timeout a member |
/warn <member> <reason> |
Issue a warning |
/warnings <member> |
View a member's warnings |
/delwarn <id> |
Delete a specific warning |
/modlog |
Query the mod action history |
/purge <amount> |
Bulk-delete messages |
| Command | Description |
|---|---|
/antiraid set |
Configure anti-raid thresholds |
/antiraid show |
Show current anti-raid settings |
/antiraid lockdown |
Manually lock down the server |
/antiraid unlock |
Lift a lockdown |
| Command | Description |
|---|---|
/tts <text> |
Speak text in your voice channel |
/soundboard <name> |
Play a sound effect |
/separate |
Split audio into vocal + instrumental tracks |
/imagine <prompt> |
Generate an image |
/freestuff setup/check/config |
Free game alert management |
/stream add/remove/list |
Twitch streamer tracking |
/twitchdrops setup/check |
Twitch Drop notifications |
/giveaway create/end/reroll |
Run a giveaway |
/xp set/reset |
Manage a member's XP |
/customcommand add/edit/delete |
Custom command management |
/reactionrole setup/remove |
Reaction role management |
/autorole add/remove |
Auto-role management |
/welcome set |
Configure welcome messages |
/auditlog set |
Configure audit log |
/userinfo [member] |
View a member's details |
/serverinfo |
View server stats |
/rate <thing> |
Rate anything from 1 to 100 |
/funconfig rate ... |
Configure /rate: mode, bar style, colour, tiers, rigged answers |
/funconfig pack ... |
Manage image packs: add/remove images, weights, bundled fallback |
/funfact |
Get a random fun fact (anyone can use) |
/ooc <message> |
Render a message as a quote image |
/oocconfig theme/style/layout/text/channels |
Configure how quote images look |
/funfactconfig setup |
Set the channel, time and timezone for the daily fact |
/funfactconfig sources |
Weight the bundled / custom / API / AI sources |
/funfactconfig add/list/remove |
Manage your server's own facts |
/funfactconfig now/preview |
Post immediately, or see one privately |
/help [category] |
Browse all commands |
- Seek / rewind —
/seek <seconds> - Queue persistence across restarts
- DJ role system
- Track history —
/history - Lyrics integration —
/lyricsvia Genius API - Autoplay / recommendations
- Apple Music support
- Per-track source badge
- Polls & voting — multi-option timed polls
- Ticket system — support ticket channels with staff routing
- Starboard — community-pinned message highlights
- Reminders — personal and channel scheduled reminders
- Birthday announcements — automated shoutouts
- PostgreSQL migration — replace SQLite for larger deployments
The dashboard exposes an unauthenticated liveness endpoint — container and uptime probes cannot log in, so it deliberately sits outside the session check. It reports only whether the Discord gateway is connected; guild counts stay behind auth.
curl http://localhost:5000/health
# {"bot_connected": true, "status": "ok"} -> 200
# {"bot_connected": false, "status": "degraded"} -> 503The Docker image uses this for its HEALTHCHECK, so a bot that is running but
disconnected shows as unhealthy rather than a reassuring "Up 3 days".
pip install -r requirements-dev.txt # runtime deps + pytest
pytest -qrequirements.txt holds runtime dependencies only, pinned to known-good versions;
test tooling lives in requirements-dev.txt and is kept out of the runtime image.
CI runs the suite plus an import check across every module in cogs/, utils/ and
dashboard/ on each push and pull request, and the image is only published if that
job passes.
For full VPS deployment with systemd, see deploy/DEPLOY.md.
MIT — free to use, modify, and self-host.
If you run this bot for others, the Terms of Service and Privacy Policy describe what the bot collects and how it is handled. Note in particular that AI chat stores message content, and that enabling it in a channel sends member messages to a third-party model provider.