Mastodon Integration

Author: Lutz Mader

Introduction

Mastodon is a federated social network node.
Mastodon has an API, that allows you to interaction with the application.

Mastodon.py is a simple Python wrapper for that API, provided as a single Python module. It aims to implement the complete public Mastodon API. As of this time, it is feature complete for Mastodon version 4.4.0.

Some usage examples can be found at https://github.com/halcy/MastodonpyExamples

Install Mastodon.py via pypi in the system.

pip install Mastodon.py

Or install Mastodon.py via pypi in your home folder.

pip install --user Mastodon.py

Note: Python 3.7 and above is required to use Mastodon.py.

Both M/Monit and Monit can quite easy be setup to send alerts to several online services. This is especially easy if the service supports a HTTP API.

This example demonstrate how to send alerts via Mastodon.

Preparation

On the Mastodon side you will first need to register a bot or app. This needs to be done once (per server and account).

Note: Older versions of Mastodon allowed logging in with username and password. Starting with version 4.4.0 Mastodon has started requiring OAuth for bots or apps.

If you are using a bot or app, you may generate a token in the Mastodon website (On Mastodon https://your-server.bot/settings/applications) and use it directly.

Go into your Mastodon website, login to the used bot or app account and switch to the "Preferences".

In "Public profile" in "Other" select "This is an automated account" to signal that the account mainly performs automated actions.
And use "Save changes" to save the setting.

In "Development" use "New application".
Set the "Application name" to "mastmonit", the "Application website" to a website, "Redirect URI" to "urn:ietf:wg:oauth:2.0:oob" (This is the suggested default) and set the "Scopes" at least to "read" and "write".
Then use "Submit" to add your new app.

Now you will see the app in the application list.
Select the app to see the application secrets "Client key", "Client secret" and "Your access token".

Note: Be careful with this data. Never share it with anyone!

Note: Keep in mind, "Your access token" will be regenerated sometimes you modify some of the setting.

Open a file called "mastmonit.secret" with your preferred editor and copy the application secrets to the file (The format is used by Mastodon.py), line by line.

Your access token
The Mastodon URL (https://your-server.bot)
The client key
The client secret

Note: The "mastmonit.secret" and the "mastmonit.py" file are stored in the same folder.

Script

Open a script file called "mastmonit.py" with your preferred editor to create a script which can be used to send Mastodon posts.

#!/usr/bin/env python3

'''
A simple script to post status notifications to a Mastodon account.
'''
from sys import exit
from os import environ
from os import path
from datetime import datetime
from mastodon import Mastodon

dirname = path.abspath(path.dirname(__file__))
secret=dirname + '/mastmonit.secret'

mastodon = Mastodon(access_token=secret)

info = ''
text = ''
resp = ''

'''
A simple notification based on the Monit mail sample.
'''
if environ.get('MONIT_SERVICE', '') != '':
    info  = 'Monit alert from ' + environ.get('MONIT_HOST') + ' for ' +  environ.get('MONIT_SERVICE') + ' ' + environ.get('MONIT_EVENT')
    text  = 'Service ' + environ.get('MONIT_SERVICE') + ' ' + environ.get('MONIT_EVENT') 
    text += '\nDate:        ' + environ.get('MONIT_DATE')
    text += '\nAction:      ' + environ.get('MONIT_ACTION')
    text += '\nHost:        ' + environ.get('MONIT_HOST')
    if environ.get('MONIT_STATUS', '') != '':
        text += '\nStatus:      ' + environ.get('MONIT_PROGRAM_STATUS')
    text += '\nDescription: ' + environ.get('MONIT_DESCRIPTION')
    text += '\nYour faithful employee,\nMonit'
else:
    now = datetime.now()
    info  = 'Monit test from ' + environ.get('HOST', '') + ' for ' +  environ.get('LOGNAME', '')
    text  = 'Service ' + environ.get('LOGNAME') + ' test notification'
    text += '\nDate:        ' + now.strftime('%a, %d %b %Y %H:%M:%S')
    text += '\nYour faithful employee,\nMonit'

try:
    resp = mastodon.status_post(status=text, visibility='public', spoiler_text=info, language='en')
except Exception as error:
    print('Something is going wrong, some details:')
    print(error)
    exit(3)

exit(0)

Test the functionality by running the "mastmonit.py" script.

cd /path/to
python3 mastmonit.py

After a short time a post should appear in the used Mastodon account.

Monit test from system for userid

Service userid test notification
Date:        Thu, 02 Apr 2026 15:15:00
Your faithful employee,
Monit

Note: This is a simplified sample Python script only.

M/Monit

Go into your M/Monit website, in "Admin", "Alerts" select "+" to "Add new rule".
Add a "Rule name" and set some conditions, then select the action "Execute program" and "i" to add some program settings.

In "Program" add the Python script to send notifications.
/bin/bash -c "cd /usr/local/etc/monit/scripts; ./mastmonit.py"

Select "Test" to test the configuration and "Close" to save the configuration.

If you test the configuration a post should appear after a short time in the used Mastodon account.

Monit alert from localhost for The name of the service generating the event A short string describing the event that occurred

Service The name of the service generating the event A short string describing the event that occurred
Date:        Thu, 02 Apr 2026 15:17:14 +0200
Action:      The name of the action which was performed by Monit
Host:        localhost
Description: A description of the event condition. I.e. why the event was sent
Your faithful employee,
Monit

Monit

The script can be used accordingly in Monit.
You can use the script in the Monit control file with the action "exec" to send an alert if a check failed via Mastodon.

check program myscript with path /usr/local/bin/myscript.sh
    if status != 0 then exec /path/to/mastmonit.sh

Note: The content of the environment variable "$MONIT_DESCRIPTION" is anything the "check program" script outputs to stdout. This make it possible to compose a detailed description of what went wrong.

Disclaimer

The use of the software takes place on your own risk.

Nobody can be made under any circumstances liable for damages to hardware and software, lost data and others directly or indirectly by the use of the software emerging damages.

If you do not agree with these conditions, you may not use or distribute this software.