Metadata-Version: 2.4
Name: mcdbus
Version: 2026.3.6.1
Summary: D-Bus MCP server — bridge Linux IPC into the Model Context Protocol
Project-URL: Source, https://git.supported.systems/warehack.ing/mcdbus
Author-email: Ryan Malloy <ryan@supported.systems>
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: dbus-fast>=3.1.2
Requires-Dist: fastmcp>=2.14.5
Description-Content-Type: text/markdown

# 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

```bash
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

```bash
claude mcp add mcdbus -- uvx mcdbus
```

With the notification confirmation fallback enabled:

```bash
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:

```bash
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
