ModBot is a Discord moderation and protection bot, open-sourced by the team behind Aternos, who run it on their own large Discord community. It keeps a full moderation history in a database and takes action on its own when members break the rules.

What it does

• Strikes with auto-punishment: warn with strikes, and set what happens at 3, 5, 10 strikes (timeout, kick, ban).
• Automod: spam and repeated-message filter, caps filter, invite-link filter, bad words with regex, link and attachment cooldowns.
• Phishing protection: detects known scam and phishing links.
• Moderation: ban, tempban, softban, kick, timeout, purge with filters, /lock and /unlock channels, moderation history per member.
• Logging: message edits and deletes, joins and leaves, every moderation action.

It does not include automatic raid detection or a captcha gate: pair it with Discord's verification level and Onboarding.

1. Create a MySQL database first

Create a New deployment > Database > MySQL. Open it and note its host, port and password (SERVER_PASSWORD). The modbot database is created automatically on the first start.

2. Create the bot on Discord

1. Open the Discord Developer Portal and click New Application.
2. Go to Bot, click Reset Token and copy it (MODBOT_AUTH_TOKEN).
3. Still on Bot, turn on Server Members Intent and Message Content Intent.
4. Go to OAuth2 > URL Generator, tick bot and applications.commands, give it Administrator (or Ban, Kick, Moderate Members, Manage Messages, Manage Channels, View Audit Log), then add it to your server.

3. Deploy and configure

Fill the variables and click Deploy. Slash commands appear on their own. Then, in your server:

• /settings log-channel, /settings message-log and /settings join-log: where to log actions, edited or deleted messages, and joins.
• /settings punishments set: what happens at each strike count (for example timeout at 3, ban at 10).
• /settings spam, /settings similar-messages, /settings caps, /settings invites: turn on the filters you want.
• /bad-word add: block words or regex patterns.
• /settings protected-roles add: roles the filters never touch (your staff).
• /settings overview: see everything at once.

Good to know

• Give it at least 384 MB of RAM.
• Optional Google API keys unlock image scanning and YouTube checks, see the ModBot CONFIGURATION.md.

ModBot

ModBot is an open source moderation bot with advanced features developed by Aternos.

It uses modern Discord features like slash-commands, context-menus, timeouts, buttons, select-menus and modals and offers everything you need for moderation. Including bad-words and auto-responses with support for regex, detecting phishing urls, temporary bans, a strike system, message logging and various other forms of automatic moderation filters.

Screenshots

Moderating users or viewing information is faster than ever thanks to buttons, modals and context menus:

ModBot will prevent accidentally punishing a user twice by warning the moderator if another moderator has punished this user in the last 5 minutes.

Add ModBot to your server

By adding the bot to your server you agree to our privacy policy.
Invite: Click me

You can view all commands by typing a slash / in the text input field. All commands and options have clear descriptions.

We also have a Discord server.
Please note: ModBot is a side project for us. We don't earn any money with it and primarily develop it for use on our own servers. We can't help with every problem and won't add features that we don't need.

Getting Started

• You can view the settings with /settings overview
• To set up a log channel use /settings log-channel <#channel>
• You can import strikes, mutes and bans from Vortex using /import
• If you want to configure a YouTube playlist, you can use /settings playlist <url>
• You can also add a Zendesk help center, using /settings helpcenter <url> to enable the /article command.

Support

You can view the usage of commands with the help command.
If you think you found a bug in ModBot then please create an issue.
For security issues please refer to the SECURITY.md.

Self Hosting

If you want to host the bot yourself you can use our pre-built docker image or install it directly. In both cases you will need a MySQL database and a Discord application:

1. Create a Discord application and enable the SERVER MEMBERS and MESSAGE CONTENT intents.
2. Add a bot to the application and copy the auth token
3. Configure the bot (see CONFIGURATION.md)
4. To invite the bot to your server replace ID with the client ID of your application https://discord.com/oauth2/authorize?client_id=ID&scope=bot%20applications.commands&permissions=1099780074646 and open the link
5. Follow the instructions for the installation method you want to use

Docker

Requirements: Docker

docker run -e MODBOT_AUTH_TOKEN="<discord-auth-token>" -e MODBOT_DATABASE_HOST="<database-host>" -e MODBOT_DATABASE_PASSWORD="<database-password>" ghcr.io/aternosorg/modbot

Direct Installation

Requirements: Node.js (v22+), a MySQL database

1. Download the code and run npm ci
2. Run npm start to start the bot

Contributing

If you want to contribute you need to fork the repository, then add your changes to your fork and then create a pull request. We also recommend looking at the Documentation of discord.js. If you have any questions create an issue or join our discord