A followbot for Mastodon, but a nice one

Lertsenem 6eeb2115c0 Corrections on language detection 1 year ago
.gitignore f047c66daa Correct gitignore 1 year ago
LICENSE 97b810a6a7 Adding MIT license 1 year ago
README.md 374f589111 Adding language blacklist support 1 year ago
main.py 6eeb2115c0 Corrections on language detection 1 year ago


Capybara Bot for Mastodon

This is a python script using the Mastodon.py library to power a Mastodon bot.

Basically, the script will search the current Federated Timeline and follow people in order to populate the said Federation Timeline a bit more (for more info on how the FTL work in Mastodon, please check the Mastodon documentation and source code). But above this crude behaviour the Capybara Bot implements several features to avoid annoying other users (a lot of people don't like being followed by robot, it turns out) :

  • it can blacklist people on demand to avoid following them
  • it respects the #nobot tag in user description
  • it does not try to follow people with a private profile
  • it avoid following people already followed by the owner
  • it sets a maximum limit on the number of people it follows
  • it unfollows people after a while
  • it can avoid following people from specific instances
  • it can avoid following people speaking specific languages
  • it's a capybara \o/

With this bot, I hope to restore trust and understanding between humans and robots. A lot of people dislike followbots, but I still think there are useful and have a role to play. I own a personnal instance and without my Capybara bot my FTL would be very lonely.

I want to play with the bot!

You will need a Mastodon account, and you'll find one running at @AutofollowBot@mastodon.lertsenem.com. Be warned though: there's no way to force it to follow you.


To run this script, you will of course need Python 3. The following modules are also required:

  • Mastodon.py, for Mastodon API interactions
  • BeautifulSoup4, for very simple HTML parsing


For a simpler installation, I recommend using a virtualenv.

$> apt install python3-virtualenv

(You'll need to adapt that command if your package manager is not apt)

$> mkdir capybarabot
$> cd capybarabot
$> git clone https://git.lertsenem.com/lertsenem/mastodon_capybarabot capybarabot
$> virtualenv -p python3 venv
$> . venv/bin/activate
(venv)$> pip install Mastodon.py beautifulsoup4
(venv)$> python capybarabot/main.py --help

usage: main.py [-h] [-V] [-v] [-i ID_FILE] [-t TOKEN_FILE] [-d DATA_FILE]
               [-l LOGIN] [-p PASSWORD] [-o OWNER] [-M MAXFOLLOW]
               [-b BLACKLISTLANGUAGE]

positional arguments:
  fullhandle            full mastodon handle

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show bot version
  -v, --verbose         more verbose logs; repeat to increase verbosity
  -i ID_FILE, --id-file ID_FILE
                        the id file
  -t TOKEN_FILE, --token-file TOKEN_FILE
                        the token file
  -d DATA_FILE, --data-file DATA_FILE
                        the data file
  -l LOGIN, --login LOGIN
                        the login to use, needed the first time
  -p PASSWORD, --password PASSWORD
                        the password to use, needed the first time
  -o OWNER, --owner OWNER
                        full mastodon handle of the bot owner
                        how much people the bot is allowed to follow
                        how many days the bot is allowed to follow people
                        how many days the bot must leave old friends alone
                        what instance the bot is not allowed to follow (can be
                        used multiple time)
                        what languages the bot is not allowed to follow (can
                        be used multiple time)


First, you'll need a mastodon account, on the instance of your choice.

Next, you can run the capybarabot with your handle ('user@instance') as an argument.

(venv)$> python capybarabot/main.py user@instance

The first time you will be prompted for your credentials, which will then be saved in mstdn_capybarabot.* files. Those files holds secrets for a full access to your account, keep them secret. You can also revoke the bot access to your account any time you want by going into your account settings and reviewing the applications permissions.

For a repeated usage, on a dedicated account for example, I recommend setting a cron task to run every minutes or so:

*/1 * * * * myuser cd path/to/capybarabot/ && ./venv/bin/python capybarabot/main.py

Note that after the first time the handle to use is saved in one of the mstdn_capybarabot.* files, so you don't need to precise it in the command line.