Ryan Malloy
c8a1ce0fdb
When MCP elicitation is unavailable (most clients), fall back to org.freedesktop.Notifications with Approve/Deny action buttons. Opt-in via MCDBUS_NOTIFY_CONFIRM=1. Silence (timeout) is denial. Fixes signal race where NotificationClosed stomped ActionInvoked result in the same event loop iteration.
124 lines
3.8 KiB
Markdown
124 lines
3.8 KiB
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
|