Skip to content
A moderation tool for Matrix
TypeScript Python Dockerfile
Branch: master
Clone or download
Latest commit d5a366a Nov 15, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
config Add a config option to reduce homeserver load during ban checks Nov 7, 2019
docs Add a moderator's guide to Mjolnir Oct 29, 2019
src Detect UISI errors from pantalaimon in the management room Nov 14, 2019
synapse_antispam Use background processes, not log contexts Nov 13, 2019
test/commands Test for ban reasons as well in autodetection Nov 14, 2019
.dockerignore Absolute bare minimum for a bot Sep 26, 2019
Dockerfile Use yarn in the docker image too Oct 31, 2019
LICENSE Initial commit Sep 26, 2019
package.json v0.1.7 Nov 14, 2019
tsconfig.json Make the [un]ban command smarter Nov 14, 2019
yarn.lock Make the [un]ban command smarter Nov 14, 2019


A moderation tool for Matrix. Visit for more information.


TODO: Describe what all this means.

Phase 1:

  • Ban users
  • ACL servers
  • Update lists with new bans/ACLs

Phase 2:

  • Pantalaimon support
  • No-op mode (for verifying behaviour)
  • Redact messages on ban (optionally)
  • More useful spam in management room
  • Command to import ACLs, etc from rooms
  • Vet rooms on startup option
  • Command to actually unban users (instead of leaving them stuck)
  • Support multiple lists

Phase 3:

  • Synapse antispam module
  • Room upgrade handling (both protected+list rooms)
  • Support community-defined scopes? (ie: no hardcoded config)
  • Riot hooks (independent of mjolnir?)

Docker (preferred)

Mjolnir is on Docker Hub as matrixdotorg/mjolnir but can be built yourself with docker build -t mjolnir ..

git clone
cd mjolnir

# Copy and edit the config. It is not recommended to change the data path.
mkdir -p /etc/mjolnir
cp config/default.yaml /etc/mjolnir/production.yaml
nano /etc/mjolnir/production.yaml

docker run --rm -it -v /etc/mjolnir:/data matrixdotorg/mjolnir:latest

Build it

This bot requires yarn and Node 10.

git clone
cd mjolnir

yarn install
yarn build

# Copy and edit the config. It *is* recommended to change the data path.
cp config/default.yaml config/development.yaml
nano config/development.yaml

node lib/index.js

Synapse Antispam Module

Using the bot to manage your rooms is great, however if you want to use your ban lists (or someone else's) on your server to affect all of your users then an antispam module is needed. Primarily meant to block invites from undesired homeservers/users, Mjolnir's antispam module is a way to interpret ban lists and apply them to your entire homeserver.

First, install the module to your Synapse python environment:

pip install -e git+

Note: Where your python environment is depends on your installation method. Visit if you're not sure.

Then add the following to your homeserver.yaml:

  module: mjolnir.AntiSpam
    # Prevent servers/users in the ban lists from inviting users on this
    # server to rooms. Default true.
    block_invites: true
    # Flag messages sent by servers/users in the ban lists as spam. Currently
    # this means that spammy messages will appear as empty to users. Default
    # false.
    block_messages: false
    # The room IDs of the ban lists to honour. Unlike other parts of Mjolnir,
    # this list cannot be room aliases or permalinks. This server is expected
    # to already be joined to the room - Mjolnir will not automatically join
    # these rooms.
      - "!"

Be sure to change the configuration to match your setup. Your server is expected to already be participating in the ban lists - if it is not, you will need to have a user on your homeserver join. The antispam module will not join the rooms for you.

If you change the configuration, you will need to restart Synapse. You'll also need to restart Synapse to install the plugin.


TODO. It's a TypeScript project with a linter.

You can’t perform that action at this time.