Maubot
A plugin-based Matrix bot system.
Last verified:
What is Maubot?
Maubot is a plugin-based Matrix bot system written in Python that allows users to create and manage bots for Matrix rooms. It provides a web management interface where administrators can upload plugins, create client accounts, and link them together as bot instances. The system is designed to be extensible through custom plugins that can add various functionalities to Matrix chat rooms.
Key features include a plugin architecture where each plugin is a .mbp file (zip archive containing maubot.yaml and Python modules), support for multiple client accounts per instance, a web-based management UI at localhost:29316/_matrix/maubot, and built-in CLI tools (mbc) for building, uploading, and managing plugins. The system supports event handlers, chat commands via decorators, and HTTP endpoints for bot functionality.
Maubot is designed for developers who want to create custom Matrix bots using Python, as well as non-developers who want to use existing plugins. It's ideal for Matrix server administrators, community managers, and anyone looking to add automated functionality to their Matrix rooms. The ecosystem includes over 100 community-made plugins ranging from utility bots (dice rolling, reminders, RSS feeds) to integrations (GitHub, GitLab, Home Assistant) and entertainment bots (anime search, comics, music).
Maubot pricing
Pricing model: Freemium
Maubot is completely free and open source. There is no paid tier or subscription. The software is self-hosted and can be deployed via Docker. All plugins in the community library are free under AGPL-3.0, MIT, or similar open source licenses. There are no usage limits, feature restrictions, or premium features.
Maubot pros
- Plugin-based architecture allows easy extension with custom functionality
- Written in Python, familiar to many developers
- Web management interface for easy bot configuration
- Supports multiple client accounts per bot instance
- mbc CLI tool for building and uploading plugins directly
- Large community plugin library with 100+ plugins available
- Plugins are self-contained .mbp files (zip archives)
- Hot-reload support - plugins reload automatically after updates
- Open source with AGPL/MIT licenses
- Works with any Matrix homeserver
- Event handlers and command decorators simplify bot development
- Supports both encrypted and unencrypted rooms
- Built-in HTTP endpoint support for webhooks
- No central plugin repository required - flexible plugin sources
- Docker deployment option for easy setup
Maubot cons
- No central plugin repository - plugins must be found manually
- Plugin development requires Python knowledge
- Reusing access tokens breaks encryption entirely
- Plugins load into global context, requiring unique module names
- Setup requires manual configuration of homeserver registration secrets
- Web UI is self-hosted, not a cloud service
- Documentation assumes prior maubot instance setup
- Limited plugin discovery - no built-in search or ratings
Frequently asked questions about Maubot
What is Maubot?
Maubot is a plugin-based Matrix bot system written in Python. It allows you to create and manage bots for Matrix rooms by uploading plugins and creating client instances. Each plugin contains the actual bot code, and instances link plugins to client accounts.
How do I install Maubot?
You can run Maubot via Docker with the command: docker run --name maubot -p 29316:29316 -v $PWD:/data:z dock.mau.dev/maubot/maubot:latest. This creates the necessary file structure including the standard configuration file.
What is a .mbp file?
A .mbp file is a maubot plugin file, which is a zip archive containing maubot.yaml (plugin metadata) and Python modules. You build it using 'mbc build' or by manually zipping the directory with 'zip -9r plugin.mbp *'.
How do I create a bot instance?
First upload a plugin (.mbp file), then create a client (Matrix account for the bot), and finally click the Create button next to Instances, select your client and plugin, invent an instance ID, and click Create.
How do I get an access token for a client?
Use the 'mbc auth' command included in maubot, or log into the Matrix account through the maubot CLI. You can also obtain it via 'docker exec -it maubot /usr/bin/python3 -m maubot.cli auth' after logging in with the admin user.
Where can I find plugins?
Plugins are available at plugins.mau.bot (the plugin list), GitHub releases (assets section), mau.dev CI pipelines, or by cloning repositories and building them yourself with 'mbc build'.
Can I create custom plugins?
Yes, you can create custom plugins by writing Python code that inherits from the Plugin class. Use decorators from maubot.handlers to define event handlers and chat commands. Initialize with 'mbc init' and build with 'mbc build'.
What is the web management interface?
The web management interface is located at http://localhost:29316/_matrix/maubot by default. You log in with credentials configured in the admins section of the config file. From here you can upload plugins, create clients, and manage instances.
How do I update a plugin?
After making changes to your plugin, use 'mbc build --upload' to build and upload it directly to the server. Any existing plugin instances will be reloaded automatically, so you can test changes immediately.
Does Maubot support encrypted rooms?
Yes, Maubot works in both encrypted and unencrypted rooms. However, you should never reuse access tokens from other clients as this will break encryption entirely and can cause other issues.