What is mcdbus?

D-Bus in 30 seconds

D-Bus is the interprocess communication system that ties a Linux desktop together. It provides a message bus where services register under well-known names (like org.freedesktop.Notifications or org.freedesktop.NetworkManager), expose objects at hierarchical paths, and publish interfaces with methods, properties, and signals. Nearly every desktop component speaks D-Bus: the notification daemon, media players, systemd, NetworkManager, UPower, bluez, KDE Plasma, GNOME Shell, and hundreds of others.

Two separate bus instances run on a typical Linux system:

• Session bus — scoped to the logged-in user. Desktop services live here: notifications, media players, file managers, portals, KDE/GNOME shell interfaces. No elevated privileges required.
• System bus — shared across all users, managed by the system. Services like systemd, NetworkManager, UDisks2, UPower, and bluez register here. Access is governed by D-Bus security policies (polkit).

The Session vs System Bus page covers the security and scoping differences in detail.

Why an MCP bridge matters

D-Bus already has CLI tools. dbus-send and busctl let you list services, introspect objects, and call methods from a terminal. But they are designed for humans typing one-off commands — they do not compose well, and they require you to already know the service name, object path, interface, and method signature before you can do anything useful.

mcdbus exposes the same D-Bus capabilities as MCP tools that an LLM client can chain together. Instead of memorizing the incantation to check your battery level through UPower, you ask Claude “what is my battery status?” and the server handles the rest: discovering the right service, walking the object tree, reading the correct properties, and formatting the response.

The key difference is introspection-first discovery. The server carries no hardcoded knowledge of specific D-Bus services. It discovers what is available on your bus at runtime, introspects the interfaces, and figures out how to interact with them. If you install a new service that exposes a D-Bus interface, mcdbus can work with it immediately.

The discovery workflow

Every interaction with mcdbus follows the same pattern, whether you are doing it explicitly or the server’s shortcut tools are doing it under the hood:

list_services  -->  list_objects  -->  introspect  -->  call_method / get_property

1. list_services — enumerate the well-known names registered on a bus. This tells you what is running and reachable.
2. list_objects — walk the object tree for a specific service. D-Bus objects are arranged in a filesystem-like hierarchy (e.g., /org/freedesktop/UPower/devices/battery_BAT0).
3. introspect — examine a specific object to see its interfaces, methods, properties, and signals. This is where you learn what you can actually do.
4. call_method / get_property — invoke a method or read a property once you know the service name, object path, interface, and member name.

The shortcut tools (send_notification, battery_status, network_status, and others) skip this workflow by hardcoding the well-known paths for common operations. They exist for convenience, but the generic discovery tools can reach anything on the bus.

How mcdbus compares to dbus-send and busctl

	dbus-send / busctl	mcdbus
Interface	Command line	MCP tools (used by Claude or any MCP client)
Discovery	Manual — you must know the service name	list_services enumerates available services
Introspection	busctl introspect output is tabular text	introspect returns structured Markdown
Composition	Shell pipes	Claude chains tools together in a single conversation
Confirmation	None (you own the terminal)	System bus calls and property mutations require user approval
Shortcuts	None — every call is fully qualified	Pre-wired tools for notifications, media, systemd, network, battery, bluetooth, KDE

mcdbus does not replace these CLI tools. It serves a different audience: LLM clients that need programmatic, composable access to D-Bus without prior knowledge of the bus layout.