Installation

Prerequisites

• Python 3.11 or later
• A running D-Bus daemon — standard on any Linux desktop (GNOME, KDE Plasma, Sway, Hyprland, etc.). If you are on a headless server without a session bus, the system bus is still available for systemd, NetworkManager, and similar services.

Install methods

From PyPI (recommended)

pip install mcdbus

Run without installing

uvx downloads and runs the package in an isolated environment. Nothing is installed globally.

uvx mcdbus

From source

git clone https://git.supported.systems/warehack.ing/mcdbus.git
cd mcdbus
uv sync
uv run mcdbus

Register with Claude Code

The simplest registration — Claude Code will start the server automatically when it needs D-Bus access:

claude mcp add mcdbus -- uvx mcdbus

To enable the desktop notification confirmation fallback (recommended if your MCP client does not support elicitation):

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

See the Confirmation Flow page for details on what this enables and when it triggers.

Environment variables

Variable	Default	Description
MCDBUS_NOTIFY_CONFIRM	unset	Enable desktop notification fallback for confirmation dialogs. When set to 1, the server sends a notification with Approve/Deny buttons if the MCP client does not support elicitation.
MCDBUS_REQUIRE_ELICITATION	unset	Hard-fail if the client does not support MCP elicitation. Overrides the notification fallback — operations that need confirmation will be rejected outright.
MCDBUS_TIMEOUT	30	D-Bus call timeout in seconds. Increase this if you interact with services that take a long time to respond (some systemd operations, large object tree walks).

Pass environment variables during registration with -e:

claude mcp add \
  -e MCDBUS_NOTIFY_CONFIRM=1 \
  -e MCDBUS_TIMEOUT=60 \
  mcdbus -- uvx mcdbus

Verify it works

Run the server directly to confirm it starts without errors:

uvx mcdbus

You should see mcdbus: D-Bus MCP server starting printed to stderr. The server is now listening for MCP messages on stdin/stdout. Press Ctrl+C to stop it.

If the D-Bus daemon is not reachable, you will see a connection error immediately. On a headless system without a session bus, the server will still start — it connects lazily when a tool is called, so a session bus error only appears when you try to use session bus tools.