g20271/kdeconnect-mcp-official

KDE Connect MCP Server

Official Model Context Protocol (MCP) server for KDE Connect integration with AI assistants like Claude Code.

🎯 Features

• Pure D-Bus Implementation - No CLI dependencies, direct communication
• Full KDE Connect Integration - 13+ tools covering all major features
• MCP Protocol Compliant - Follows official JSON-RPC 2.0 specification
• AI Assistant Ready - Works with Claude Code, Cline, and other MCP clients

📦 Available Tools

Device Management

• kdeconnect_list_devices - List paired devices
• kdeconnect_get_battery - Get battery status

Media Control

• kdeconnect_get_now_playing - Get current media info
• kdeconnect_media_control - Control playback (Play/Pause/Next/Previous/Stop)
• kdeconnect_get_media_players - List available players
• kdeconnect_set_media_player - Switch active player
• kdeconnect_detect_active_player - Auto-detect playing app

Communication

• kdeconnect_send_notification - Send notifications
• kdeconnect_get_notifications - Get active notifications

File Transfer

• kdeconnect_share_url - Share URLs
• kdeconnect_share_file - Send files to device
• kdeconnect_list_received_files - List received files
• kdeconnect_open_file - Open received files

Device Control

• kdeconnect_ring_device - Ring device to find it

🚀 Quick Start

Prerequisites

# Install dependencies
sudo apt install python3-dbus python3-gi kdeconnect

# Ensure KDE Connect daemon is running
ps aux | grep kdeconnect

Installation

# Clone repository
git clone https://github.com/YOUR_USERNAME/kdeconnect-mcp-official.git
cd kdeconnect-mcp-official

# Make executable
chmod +x mcp_server_official.py

# Test
python3 test_mcp_official.py

Claude Code Setup

1. Open Claude Code configuration:

   nano ~/.config/Claude/claude_desktop_config.json
   

2. Add MCP server:

   {
     "mcpServers": {
       "kdeconnect": {
         "command": "python3",
         "args": [
           "/path/to/kdeconnect-mcp-official/mcp_server_official.py"
         ]
       }
     }
   }
   

3. Restart Claude Code

💡 Usage Examples

In Claude Code

Device Control:

• "List my KDE Connect devices"
• "What's my phone's battery level?"
• "Ring my phone to find it"

Media Control:

• "What's currently playing on my phone?"
• "Skip to the next song"
• "Pause the music on my device"
• "Detect which player is active"

Communication:

• "Send a notification: Meeting in 5 minutes"
• "Show me all notifications on my phone"

File Transfer:

• "Send this file to my phone: /path/to/file.pdf"
• "Share this URL with my device: https://example.com"
• "List recently received files from my phone"

🧪 Testing

# Run comprehensive test suite
python3 test_mcp_official.py

# Manual test (get device list)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kdeconnect_list_devices","arguments":{}}}' | python3 mcp_server_official.py

📊 Architecture

AI Assistant (Claude Code)
         ↓ JSON-RPC 2.0
   MCP Server (Python)
         ↓ D-Bus
   KDE Connect Daemon
         ↓ Network Protocol
   Android/iOS Device

Key Components

• Pure D-Bus Communication - Direct integration with KDE Connect daemon
• MCP Protocol Handler - JSON-RPC 2.0 request/response
• Tool Definitions - JSON Schema for all available operations
• Session Bus Access - User-level D-Bus communication

🔧 Technical Details

MCP Protocol Version

2024-11-05

Supported Methods

• initialize - Server initialization
• tools/list - List available tools
• tools/call - Execute tool

D-Bus Interface

• Service: org.kde.kdeconnect
• Path: /modules/kdeconnect/devices/{id}/{plugin}
• Plugins: mprisremote, notifications, share, ping, battery, findmyphone

📝 Requirements

• Python 3.8+
• KDE Connect 24.x+
• D-Bus session bus
• python3-dbus
• python3-gi (GObject introspection)

🐛 Troubleshooting

MCP server not recognized

# Check JSON syntax
cat ~/.config/Claude/claude_desktop_config.json | jq .

# Verify file permissions
ls -la mcp_server_official.py

# Check path is absolute
realpath mcp_server_official.py

D-Bus errors

# Ensure KDE Connect is running
systemctl --user status kdeconnectd

# Or start manually
/usr/lib/x86_64-linux-gnu/libexec/kdeconnectd &

Device not found

# List paired devices
kdeconnect-cli --list-available

# Refresh connections
kdeconnect-cli --refresh

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

📄 License

GPL-3.0-or-later - See LICENSE file for details

🙏 Acknowledgments

• KDE Connect - Amazing device integration
• Model Context Protocol - AI assistant protocol
• Anthropic - Claude AI and Claude Code

📧 Contact

Issues: https://github.com/YOUR_USERNAME/kdeconnect-mcp-official/issues

Made with ❤️ for the KDE and AI communities