Content
# 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:
```bash
git clone https://github.com/subpop/mcp_dbus.git
cd mcp_dbus
```
2. Build the project:
```bash
cargo build --release
```
3. The binary will be available at `target/release/mcp_dbus`
### Installing with Cargo
```bash
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`
```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:
```json
{
"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
```json
{
"service": "org.freedesktop.systemd1",
"object_path": "/org/freedesktop/systemd1",
"interface": "org.freedesktop.systemd1.Manager",
"method": "ListUnits",
"args": []
}
```
#### Get System Hostname
```json
{
"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
```json
{
"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](https://flathub.org/en/apps/org.gnome.dspy) 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
```bash
cargo test
```
### Building Documentation
```bash
cargo doc --open
```
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) 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
