Matrix-mcnt

Matrix message count outputs the number of unread messages of all or of specified rooms to stdout. This can be useful to place in your status bar to see if you have new messages without explicitly checking in the app.

Usage

python3 matrix-mcnt.py --username USERNAME [options]

Required arguments:
  --username USERNAME     Your Matrix username without the @username:matrix.org format

Optional arguments:
  --bg                  Syncronize in the background
  --pass-path           A path to a password-store file (e.g., 'Matrix/my_user_name/pass')
  --homeserver SERVER   Matrix homeserver (default: matrix.org)
  --rooms ROOM_IDS      List of room IDs to include (all non-specified rooms will be excluded)
  --exclude-rooms IDS   List of room IDs to exclude
  --print-rooms         Print all available rooms and their unread counts

Examples: - Get unread count for all rooms using pass:

$ python3 matrix-mcnt.py --username 'myusername' --pass-path 'Matrix/myusername/passwd'
42
$ python3 matrix-mcnt.py --username 'myusername' --pass-path 'Matrix/myusername/access-token'
42

Using a custom home-server without pass and excluding a room from the result:

$ python3 matrix-mcnt.py --username 'myusername' --homeserver 'matrix.myserver.com' --exclude-room '!Abcdefghijklmnopqr'
Password for @myusername:matrix.myserver.com:
38 # 38 unread messages not including those from '!Abcdefghijklmnopqr'

Include only a specific room

$ python3 matrix-mcnt.py --username 'myusername' --room '!Abcdefghijklmnopqr'
Password for @myusername:matrix.org:
4

Pipe stderr to /dev/null while running in the background

$ (python3.13 matrix-mcnt.py --username 'myuser' --pass-path 'Matrix/myuser/passwd' --bg) 2> /dev/null
1 # Updates every FETCH_DELAY seconds

Install

Prerequisites - Python 3.x - matrix-nio - (Optional) pass to prevent password prompting
Clone the repo and satisfy its dependencies

git clone https://github.com/arachnida82/matrix-mcnt
cd matrix-mcnt
python3.13 -m venv env
source env/bin/activate
pip install -r requirements.txt

Notes

Rate limits. Depends on the home servers configuration. 30 seconds should be sufficient, but you can update FETCH_DELAY in matrix-mcnt.py

Licensing and Acknowledgement

The Matrix Message Count program (matrix-mcnt) is licensed under GPL-3.0. It uses matrix-nio under the Apache-2.0 license and Internet Systems Consortium license (ISC). A copy of the GPL-3.0 license has been produced below.