Send Notifications

mcdbus provides a send_notification shortcut tool that sends desktop notifications through the standard org.freedesktop.Notifications interface on the session bus. Any notification daemon that implements this spec (dunst, mako, GNOME Shell, KDE Plasma) will display them.

Basic usage

The only required parameter is the summary (title):

“Send me a notification that says the build is done.”

send_notification(summary="Build complete")

This sends a notification with the title “Build complete”, no body text, the default icon, and a 5-second timeout.

Adding body text

The body parameter accepts plain text or basic HTML markup (depending on your notification daemon):

“Notify me that the deploy finished with details about what was deployed.”

send_notification(
    summary="Deploy finished",
    body="Pushed v2026.03.06 to production. All health checks passing."
)

Choosing an icon

The icon parameter follows the freedesktop icon naming specification. Your desktop theme provides the actual icon files. Common names include:

Icon name	Typical use
dialog-information	General information
dialog-warning	Warning conditions
dialog-error	Error conditions
process-completed	Task completion
network-wireless	Network-related
battery-low	Battery alerts

“Send a warning notification about high memory usage.”

send_notification(
    summary="High memory usage",
    body="System memory at 92%. Consider closing unused applications.",
    icon="dialog-warning"
)

You can also pass an absolute file path to use a custom icon image:

send_notification(
    summary="Screenshot saved",
    icon="/tmp/screenshot-thumbnail.png"
)

Controlling display duration

The timeout parameter sets how long the notification stays visible, in milliseconds. The default is 5000 (5 seconds).

send_notification(
    summary="Quick heads-up",
    body="This disappears fast.",
    timeout=2000
)

A timeout of 0 tells the notification server to use its own default duration. Some servers treat 0 as “never expire” — the notification stays until the user dismisses it.

Note

Not all notification daemons respect the timeout value. Some (like GNOME Shell) ignore it entirely and use their own fixed duration. This is permitted by the spec.

What happens under the hood

The send_notification tool calls org.freedesktop.Notifications.Notify on the session bus with the D-Bus signature susssasa{sv}i. The parameters map to:

Position	Signature	Parameter	Value
0	s	app_name	"mcdbus"
1	u	replaces_id	0 (new notification)
2	s	app_icon	Your icon value
3	s	summary	Your summary value
4	s	body	Your body value
5	as	actions	[] (empty)
6	a{sv}	hints	{} (empty)
7	i	expire_timeout	Your timeout value

The server returns a notification ID (an unsigned integer). The tool reports this ID in its response.

Replacing an existing notification

The shortcut tool always sends replaces_id=0, which creates a new notification. To update or replace an existing notification, use call_method directly and pass the notification ID you received from a previous call:

“Update notification 42 with new progress information.”

call_method(
    bus="session",
    service="org.freedesktop.Notifications",
    object_path="/org/freedesktop/Notifications",
    interface="org.freedesktop.Notifications",
    method="Notify",
    args='["mcdbus", 42, "", "Build progress", "Step 3 of 5 complete", [], {}, 5000]',
    signature="susssasa{sv}i"
)

Closing a notification

To programmatically close a notification by its ID:

call_method(
    bus="session",
    service="org.freedesktop.Notifications",
    object_path="/org/freedesktop/Notifications",
    interface="org.freedesktop.Notifications",
    method="CloseNotification",
    args='[42]',
    signature="u"
)

Querying the notification server

To find out which features your notification daemon supports:

call_method(
    bus="session",
    service="org.freedesktop.Notifications",
    object_path="/org/freedesktop/Notifications",
    interface="org.freedesktop.Notifications",
    method="GetServerInformation"
)

This returns the server name, vendor, version, and spec version. You can also call GetCapabilities to see which features (like body-markup, actions, persistence) are supported.