subpop/mcp_dbus

MCP D-Bus Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with D-Bus services on Linux systems. This server provides a bridge between MCP clients (like Claude Desktop or Visual Studio Code) and the D-Bus inter-process communication system.

D-Bus is a message bus system used for inter-process communication on Linux systems. This MCP server allows AI assistants to call methods on D-Bus services, enabling interaction with system services, desktop applications, and other D-Bus-enabled software.

Features

• D-Bus Method Calls: Execute methods on any accessible D-Bus service
• Rich Type Support: Supports all basic D-Bus types including:
  • Integers (int16, int32, int64, uint16, uint32, uint64)
  • Floating point (double)
  • Strings and object paths
  • Booleans and bytes
  • Arrays of basic types
  • Dictionaries with string keys
  • Signatures
• System Bus Access: Connects to the system D-Bus for system service interaction
• JSON Response Format: Returns D-Bus method results as JSON for easy consumption

Installation

Prerequisites

• Rust (latest stable version)
• Linux system with D-Bus
• Access to system D-Bus (may require appropriate permissions)

Building from Source

1. Clone the repository:

   git clone https://github.com/subpop/mcp_dbus.git
   cd mcp_dbus
   

2. Build the project:

   cargo build --release
   

3. The binary will be available at target/release/mcp_dbus

Installing with Cargo

cargo install --git https://github.com/subpop/mcp_dbus.git

Configuration

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dbus": {
      "command": "/path/to/mcp_dbus",
      "args": []
    }
  }
}

Replace /path/to/mcp_dbus with the actual path to your compiled binary.

VS Code with MCP Extension

If using VS Code with an MCP extension, add the server configuration to your settings:

{
  "mcp.servers": {
    "dbus": {
      "command": "/path/to/mcp_dbus",
      "args": []
    }
  }
}

Usage

Once configured, the server provides the following tool to MCP clients:

call_method

Calls a method on a D-Bus service.

Parameters:

• service: The D-Bus service name (e.g., "org.freedesktop.systemd1")
• object_path: The D-Bus object path (e.g., "/org/freedesktop/systemd1")
• interface: The D-Bus interface name (e.g., "org.freedesktop.systemd1.Manager")
• method: The method name to call (e.g., "ListUnits")
• args: Array of arguments in the format "type:value"

Argument Format

Arguments are specified as strings in the format "type:value":

Basic Types

• "string:hello" - String value
• "int32:42" - 32-bit integer
• "uint32:42" - 32-bit unsigned integer
• "int64:1234567890" - 64-bit integer
• "boolean:true" - Boolean value
• "double:3.14" - Double precision float
• "byte:255" - Single byte (0-255)
• "objpath:/org/freedesktop/systemd1" - D-Bus object path
• "signature:s" - D-Bus type signature
• "variant:string:hello" - Variants

Arrays

• "array:string:hello,world,test" - Array of strings
• "array:int32:1,2,3,4" - Array of integers
• "array:boolean:true,false,true" - Array of booleans

Dictionaries

• "dict:string:string:key1,value1,key2,value2" - String-to-string dictionary
• "dict:string:int32:count,42,size,100" - String-to-integer dictionary
• "dict:string:variant:name,string:John,age,int32:42" - String-to-variant dictionary

Example Usage

Here are some example D-Bus method calls you can make through the MCP client:

List SystemD Units

{
  "service": "org.freedesktop.systemd1",
  "object_path": "/org/freedesktop/systemd1",
  "interface": "org.freedesktop.systemd1.Manager",
  "method": "ListUnits",
  "args": []
}

Get System Hostname

{
  "service": "org.freedesktop.hostname1",
  "object_path": "/org/freedesktop/hostname1",
  "interface": "org.freedesktop.DBus.Properties",
  "method": "Get",
  "args": [
    "string:org.freedesktop.hostname1",
    "string:Hostname"
  ]
}

Send Desktop Notification

{
  "service": "org.freedesktop.Notifications",
  "object_path": "/org/freedesktop/Notifications",
  "interface": "org.freedesktop.Notifications",
  "method": "Notify",
  "args": [
    "string:mcp-dbus",
    "uint32:0",
    "string:",
    "string:Test Notification",
    "string:This is a test message from MCP D-Bus",
    "array:string:",
    "dict:string:string:",
    "int32:5000"
  ]
}

Common D-Bus Services

Here are some commonly available D-Bus services you can interact with:

• systemd: org.freedesktop.systemd1 - System and service management
• NetworkManager: org.freedesktop.NetworkManager - Network configuration
• UPower: org.freedesktop.UPower - Power management information
• Notifications: org.freedesktop.Notifications - Desktop notifications
• Login1: org.freedesktop.login1 - Login and session management
• Hostname1: org.freedesktop.hostname1 - System hostname information

Use tools like D-Spy or busctl to explore available services and their methods.

Troubleshooting

Permission Issues

If you encounter permission errors:

1. Ensure your user has access to the system D-Bus
2. Some operations may require elevated privileges
3. Check D-Bus service policies in /etc/dbus-1/system.d/

Common Errors

• "Failed to connect to D-Bus": D-Bus daemon not running or permission issues
• "Failed to call method": Invalid service name, object path, interface, or method
• "Failed to parse arguments": Incorrect argument format or type specification

Development

Running Tests

cargo test

Building Documentation

cargo doc --open

License

This project is licensed under the MIT License. See the file for details.

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

Repository

• Source: https://github.com/subpop/mcp-dbus
• Issues: https://github.com/subpop/mcp-dbus/issues