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)

1. help - Show available capabilities and tools

2. notify - Send desktop notifications

3. status - Get system status (battery, network, etc.)

4. discover - Explore available tool categories

5. list_services - List all D-Bus services

6. introspect - Explore service interfaces and methods

7. call_method - Call D-Bus methods (with security controls)

Desktop Tools (When Display Available)

8. clipboard_read/clipboard_write - Clipboard access (KDE/GNOME)

9. capture_active_window - Screenshot the active window 📸

10. capture_screen - Screenshot entire screen 📸

11. 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.

Documentation

📚 Full Documentation

Key Documents:

• Concept Overview - Understand the vision

• Architecture Overview - How it works

• Security Model - Security-first design

• Examples - See it in action

For Developers:

• CLAUDE.md - Development guidelines

• Project Structure - Code organization

• System Profiles - Adapt to any Linux system

For Operators:

• Connection Architecture - Deployment options

• Privilege Model - Security boundaries

• System Roles - Workstation vs Server

Status

🚧 Alpha - Basic functionality implemented, ready for testing

What's Working:

• ✅ Core MCP server with stdio transport

• ✅ SystemD service integration with Unix socket support

• ✅ System profile auto-detection (KDE/Arch tested)

• ✅ Basic tools: notify, clipboard, status, help

• ✅ Screenshot capability with file management

• ✅ Security policies and rate limiting

• ✅ Progressive tool disclosure

🚀 Roadmap

See our comprehensive Development Roadmap for planned features including:

• 🎵 Media control and window management

• 🖥️ Server fleet management tools

• 🐧 GNOME, Sway, and Ubuntu profiles

• 🔌 Native socket support

• 🤖 AI-specific enhancements

• And much more!

License

MIT License - see LICENSE for details

Contributing

We welcome contributions! Areas where help is especially appreciated:

• 🐧 System Profiles: Add support for your distro/desktop environment

• 🔧 Tools: Implement new D-Bus tools for common operations

• 📖 Documentation: Improve guides and examples

• 🧪 Testing: Test on different Linux systems

See CLAUDE.md for development guidelines.