dbus-mcp

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.