mcdbus

D-Bus MCP server — bridge Linux IPC into the Model Context Protocol.

Gives Claude (or any MCP client) native tool access to session and system D-Bus services through introspection-first discovery. No hardcoded service knowledge — the server discovers what's available on your bus at runtime.

Install

pip install mcdbus
# or
uvx mcdbus

Requires Python 3.11+ and a running D-Bus daemon (standard on any Linux desktop).

Add to Claude Code

claude mcp add mcdbus -- uvx mcdbus

With the notification confirmation fallback enabled:

claude mcp add -e MCDBUS_NOTIFY_CONFIRM=1 mcdbus -- uvx mcdbus

How it works

The server exposes D-Bus through a discovery workflow:

list_services  →  list_objects  →  introspect  →  call_method / get_property

Two buses are available:

• session — user desktop services (notifications, media players, KDE, portals)
• system — system services (systemd, NetworkManager, UDisks2, UPower, bluez)

Tools

Discovery

Tool	Description
list_services	List well-known service names on a bus
introspect	Show interfaces, methods, properties, and signals for a D-Bus object
list_objects	Walk the object tree for a service (bounded BFS)

Interaction

Tool	Description
call_method	Call any D-Bus method and return the result
get_property	Read a single property value
set_property	Set a property value (requires confirmation)
get_all_properties	Read all properties on an interface

Shortcuts

Pre-wired tools for common operations — no introspection needed:

Tool	Description
send_notification	Send a desktop notification
list_systemd_units	List systemd units, with optional glob filter
media_player_control	Control MPRIS2 media players (play, pause, next, stop)
network_status	NetworkManager connection status
battery_status	Battery percentage and charging state via UPower
bluetooth_devices	Paired and discovered devices via bluez
kwin_windows	Open windows from KDE KWin

Resources

URI	Description
dbus://{bus}/services	Live list of service names
dbus://{bus}/{service}/objects	Object tree (max 200 nodes)
dbus://{bus}/{service}/{path}/interfaces	Interfaces at an object path

Prompts

Prompt	Description
explore_service	Guided walkthrough of a D-Bus service
debug_service	Diagnose issues with a service

Confirmation model

Sensitive operations require explicit user approval before executing:

• System bus method calls — confirmed before execution
• Property mutations (set_property) — confirmed on any bus

The server tries three confirmation methods in order:

1. MCP elicitation — native protocol support (if the client implements it)
2. Desktop notification — Approve/Deny buttons via org.freedesktop.Notifications (opt-in, see below)
3. Proceed with warning — logs to stderr and allows the operation

Desktop notification fallback

When the MCP client doesn't support elicitation (most don't yet, including Claude Code), the server can fall back to desktop notifications with action buttons. The notification stays up for 60 seconds. No response is treated as a denial.

Enable with:

MCDBUS_NOTIFY_CONFIRM=1

Environment variables

Variable	Default	Description
MCDBUS_NOTIFY_CONFIRM	unset	Enable desktop notification fallback for confirmation
MCDBUS_REQUIRE_ELICITATION	unset	Hard-fail if client doesn't support MCP elicitation (overrides notification fallback)
MCDBUS_TIMEOUT	30	D-Bus call timeout in seconds

License

MIT