dbus-mcp

Name: dbus-mcp
Availability: InStock
Author: Aaron Bockelie

Model Context Protocol server that bridges AI assistants to Linux D-Bus, enabling system control through desktop notifications, clipboard, screenshots, and service introspection with configurable security levels.

GitHub

GitHub Stars

User Rating

Not Rated

Forks

Issues

Views

Favorites

README

D-Bus MCP Server

A Model Context Protocol (MCP) server that exposes D-Bus functionality to AI assistants, enabling deep integration with Linux systems - from vacuum cleaners to supercomputers.

Vision

This project enables AI assistants to interact with Linux systems through the standardized D-Bus interface. While Linux runs on everything from vacuum cleaners to supercomputers, this MCP server focuses on two major system roles where D-Bus integration provides the most value:

1. Workstation Role (Interactive Desktop Systems)

For Linux desktop/laptop users, AI assistants can enhance productivity by:

Managing clipboard content and history
Sending desktop notifications
Taking and analyzing screenshots
Controlling media playback
Monitoring system resources
Integrating with desktop applications

2. Dedicated System Role (Servers, Appliances, Embedded)

For systems with specific purposes (web servers, routers, NAS, IoT devices), AI operates as a "maintenance robot" that can:

Connect to servers via standardized D-Bus interfaces
Discover available services and capabilities
Monitor system health and performance
Analyze logs and diagnose issues
Perform authorized remediation actions
Generate reports across server fleets

Key Features

Secure by Design: Multiple privilege levels, PolicyKit integration, audit logging
Desktop Environment Agnostic: Uses freedesktop.org standards where possible
Discoverable: Services self-document through D-Bus introspection
Type-Safe: D-Bus provides strong typing for all operations
Rate Limited: Prevents abuse of system resources

Architecture

The MCP server acts as a bridge between AI assistants and the D-Bus system:

graph LR
    subgraph "AI Layer"
        A[fa:fa-robot AI Assistant<br/>Claude, GPT, etc.]
    end
    
    subgraph "Protocol Layer"
        B[fa:fa-exchange-alt MCP Protocol<br/>JSON-RPC over stdio/SSE]
    end
    
    subgraph "Bridge Layer"
        C[fa:fa-server D-Bus MCP Server<br/>Security & Translation]
    end
    
    subgraph "System Layer"
        D1[fa:fa-desktop Session Bus<br/>Desktop Services]
        D2[fa:fa-cog System Bus<br/>System Services]
    end
    
    A <-->|"Tools & Resources"| B
    B <-->|"Request/Response"| C
    C <-->|"Method Calls"| D1
    C <-->|"Monitoring"| D2
    
    style A fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#000
    style B fill:#f3e5f5,stroke:#4a148c,stroke-width:2px,color:#000
    style C fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
    style D1 fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#000
    style D2 fill:#ffebee,stroke:#b71c1c,stroke-width:2px,color:#000

🔒 Security Model - Safety First

The D-Bus MCP server implements configurable safety levels to balance functionality with security:

🟢 HIGH Safety (Default) - Safest Choice

Essential operations with minimal risk: clipboard, notifications, media control, system monitoring

🟡 MEDIUM Safety - Productivity Mode

Adds text editing, file management, and browser operations for AI-assisted workflows

🔴 LOW Safety (Future) - Advanced Users

Maximum functionality for expert users who understand the risks

⚫ NEVER ALLOWED - Hard Security Boundaries

Operations like shutdown, disk formatting, and package management are always blocked

# Choose your safety level
python -m dbus_mcp --safety-level high    # Default - safest
python -m dbus_mcp --safety-level medium  # Productivity features

📖 Complete Security Guide

Quick Start

📖 Complete Quick Start Guide

🚀 Recommended: Production Installation with systemd

For production use, we recommend running D-Bus MCP as a systemd service with Unix socket support:

# Clone and install with systemd service
git clone https://github.com/aaronsb/dbus-mcp.git
cd dbus-mcp
./install.sh --prod-only

# Configure safety level
sudo nano /etc/dbus-mcp/config  # Set SAFETY_LEVEL="medium"

# Start the service
systemctl --user start dbus-mcp-standalone.service
systemctl --user enable dbus-mcp-standalone.service

# Configure your MCP client with:
# socat UNIX-CONNECT:$XDG_RUNTIME_DIR/dbus-mcp.sock STDIO

# KDE Users: Enable screenshot permission
sudo cp systemd/dbus-mcp-screenshot.desktop /usr/share/applications/

📖 SystemD Mode Guide - Complete setup and configuration

🛠️ Alternative: Development Mode

For development or testing, you can run directly:

# Quick development setup
./quickstart.sh

# Test the installation
python test_installation.py

# Run directly
python -m dbus_mcp --safety-level medium

The Quick Start Guide includes:

System requirements and prerequisites
Multiple installation methods (systemd recommended for production)
Configuration for Claude Desktop, Claude Code, and VS Code
Troubleshooting tips

Core Tools

The server starts with essential tools for D-Bus interaction:

Basic Tools (Always Available)

help - Show available capabilities and tools
notify - Send desktop notifications
status - Get system status (battery, network, etc.)
discover - Explore available tool categories
list_services - List all D-Bus services
introspect - Explore service interfaces and methods
call_method - Call D-Bus methods (with security controls)

Desktop Tools (When Display Available)

clipboard_read/clipboard_write - Clipboard access (KDE/GNOME)
capture_active_window - Screenshot the active window 📸
capture_screen - Screenshot entire screen 📸
list_screenshot_files - List captured screenshots

📸 Screenshot Capability

The server can now capture screenshots through D-Bus, storing them as temporary files with reference IDs. This enables AI assistants to:

Capture windows or screens for visual context
Document UI states
Create visual bug reports
Guide users with annotated screenshots

KDE Users: To enable screenshots, install the desktop entry file:

sudo cp systemd/dbus-mcp-screenshot.desktop /usr/share/applications/

See the Screenshot Authorization Guide for details.

Screenshots are stored in ~/.cache/dbus-mcp/screenshots/ with proper user permissions, ensuring privacy and persistence. See Screenshot Authorization for KDE setup.