Skip to content
mcdbus

First Steps

This tutorial walks through the discovery workflow hands-on. You will list services, introspect an object, call a method, and send a desktop notification — all through mcdbus tools in a Claude conversation.

Make sure you have installed mcdbus and registered it with Claude Code before continuing.

1. List services on the session bus

Section titled “1. List services on the session bus”

Start by seeing what is available. Ask Claude to list services, or it will call the tool directly:

> What D-Bus services are running on my session bus?

Claude calls list_services(bus="session") and gets back something like:

## D-Bus session bus — 42 services


- `org.freedesktop.DBus`
- `org.freedesktop.Notifications`
- `org.freedesktop.portal.Desktop`
- `org.kde.KWin`
- `org.kde.StatusNotifierWatcher`
- `org.kde.kglobalaccel`
- `org.kde.plasmashell`
- `org.mpris.MediaPlayer2.firefox`
...

The exact list depends on your desktop environment and running applications. Every Linux desktop will have org.freedesktop.Notifications available — that is the one we will explore next.

2. Introspect the Notifications service

Section titled “2. Introspect the Notifications service”

Now look at what the notification service can do:

> Introspect the org.freedesktop.Notifications service at /org/freedesktop/Notifications

Claude calls:

introspect(
  bus="session",
  service="org.freedesktop.Notifications",
  object_path="/org/freedesktop/Notifications"
)

The output shows the interface, its methods, properties, and signals:

## `org.freedesktop.Notifications` at `/org/freedesktop/Notifications`


### Interface: `org.freedesktop.Notifications`


**Methods:**
- `Notify(app_name: s, replaces_id: u, app_icon: s, summary: s, body: s, actions: as, hints: a{sv}, expire_timeout: i) -> id: u`
- `CloseNotification(id: u)`
- `GetCapabilities() -> capabilities: as`
- `GetServerInformation() -> name: s, vendor: s, version: s, spec_version: s`

This is the D-Bus introspection XML rendered into a readable format. You can see the Notify method takes 8 arguments (application name, icon, summary, body, etc.) and returns a notification ID. The GetServerInformation method takes no arguments and returns four strings.

3. Call GetServerInformation

Section titled “3. Call GetServerInformation”

Try a simple method call first — one that takes no arguments and has no side effects:

> Call GetServerInformation on the Notifications service

Claude calls:

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

The response depends on your notification daemon. On KDE Plasma:

["Plasma", "KDE", "2.0", "1.2"]

On a system running dunst:

["dunst", "knopwob", "1.11.0", "1.2"]

The four values are the server name, vendor, version, and the notification spec version it implements.

4. Send a test notification

Section titled “4. Send a test notification”

Now use the shortcut tool to send a notification without having to specify all 8 arguments to the Notify method manually:

> Send me a test notification saying "Hello from mcdbus"

Claude calls:

send_notification(
  summary="Hello from mcdbus",
  body="Your D-Bus bridge is working!"
)

A notification appears on your desktop. The tool returns:

Notification sent (id: 47)

The notification ID can be used to replace or close the notification later through the raw call_method tool.

5. What to do next

Section titled “5. What to do next”

You have completed the core discovery workflow: list services, introspect an object, call a method. From here: