G1 UART MCP Server
A Model Context Protocol (MCP) server that provides tools for communicating with G1 devices over Bluetooth Low Energy (BLE) using the Nordic UART protocol.
Overview
This project implements an MCP server that enables AI assistants and other MCP clients to:
- Scan for G1 Bluetooth devices
- Connect to G1 devices
- Send and receive messages using the Nordic BLE UART protocol
- Monitor connection status and device information
- NEW: Automatically monitor and maintain stable connections
- NEW: Auto-reconnect on connection loss
- NEW: Configurable connection monitoring parameters
The server is particularly designed for working with Even G1 devices, which appear to be paired left/right devices for audio applications.
Features
- Device Discovery: Scan for available G1 devices with automatic side detection (left/right)
- BLE Connection Management: Connect, disconnect, and monitor connection status
- Nordic UART Protocol: Full support for the Nordic UART service (6E400001-B5A3-F393-E0A9-E50E24DCCA9E)
- Message Communication: Send hex-formatted messages and receive responses
- MCP Integration: Seamless integration with MCP-compatible AI assistants and tools
- 🆕 Connection Monitoring: Automatic heartbeat and health checks to maintain stable connections
- 🆕 Auto-Reconnection: Automatically attempt to reconnect if the connection is lost
- 🆕 Configurable Settings: Adjustable heartbeat intervals, timeouts, and reconnection parameters
Prerequisites
- Python 3.8+
- macOS (tested on darwin 24.3.0)
- Bluetooth Low Energy support
- Access to G1 devices
Installation
Option 1: Quick Start with uvx (Recommended)
Run directly from GitHub without installation:
uvx --from git+https://github.com/danroblewis/g1_uart_mcp g1-device-mcp
For MCP Configuration:
Add this to your mcp.json:
{
"mcpServers": {
"g1-device-mcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/danroblewis/g1_uart_mcp",
"g1-device-mcp"
]
}
}
}
Option 2: Local Installation
- Clone the repository:
git clone <repository-url>
cd g1_uart_mcp
- Create a virtual environment:
python3 -m venv venv
source venv/bin/activate # On macOS/Linux
- Install dependencies:
pip install -r requirements.txt
Configuration
The MCP server is configured via mcp.json. For the recommended uvx method, use this configuration:
{
"mcpServers": {
"g1-device-mcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/danroblewis/g1_uart_mcp",
"g1-device-mcp"
]
}
}
}
Alternative: Local Installation If you prefer local installation, update the paths to match your system:
{
"mcpServers": {
"g1-device-mcp": {
"command": "/path/to/your/venv/bin/python",
"args": [
"/path/to/your/g1_uart_mcp/mcp_server.py"
]
}
}
}
Usage
Starting the MCP Server
The server can be started directly or through an MCP client:
With uvx (Recommended)
uvx --from git+https://github.com/danroblewis/g1_uart_mcp g1-device-mcp
Local Installation
python mcp_server.py
Available Tools
1. Scan for G1 Devices
scan_g1_devices()
Scans for available G1 devices and returns a list with device information including name, ID, side (left/right), and signal strength.
2. Connect to G1 Device
connect_g1_device(address)
Connects to a specific G1 device by its address or UUID.
3. Get Connection Status
get_g1_connection_status()
Returns detailed information about the current connection including device details, UART service availability, and connection monitoring statistics.
4. Send Message
send_g1_message(hex_data)
Sends a hex-formatted message to the connected device and waits for a response. Now includes automatic connection health checks and reconnection attempts.
5. Disconnect
disconnect_g1_device()
Disconnects from the currently connected device.
6. 🆕 Configure Connection Settings
configure_g1_connection_settings(
heartbeat_interval=5.0,
connection_timeout=30.0,
auto_reconnect_enabled=True,
max_reconnect_attempts=3,
reconnect_delay=2.0
)
Configures connection monitoring and auto-reconnection parameters.
Example Workflow
-
Scan for devices:
devices = scan_g1_devices() # Returns list of available G1 devices -
Connect to a device:
result = connect_g1_device("device_uuid_or_address") -
Configure connection monitoring (optional):
configure_g1_connection_settings( heartbeat_interval=3.0, # More frequent heartbeats auto_reconnect_enabled=True ) -
Send a message:
response = send_g1_message("2506") # Sends command 0x25 with data 0x06 # Connection is automatically monitored and maintained -
Check status:
status = get_g1_connection_status() # Now includes connection duration, last activity, and reconnection info -
Disconnect:
disconnect_g1_device()
Connection Monitoring & Auto-Reconnection
How It Works
The enhanced MCP server now includes robust connection management:
- Heartbeat Monitoring: Sends periodic ping messages (every 5 seconds by default) to keep the connection alive
- Health Checks: Regularly verifies the connection is still responsive
- Auto-Detection: Automatically detects when the connection is lost
- Smart Reconnection: Attempts to reconnect up to 3 times with configurable delays
- Background Monitoring: All monitoring happens in the background without blocking message sending
Configuration Options
heartbeat_interval: How often to send heartbeat messages (default: 5 seconds)connection_timeout: Maximum connection duration before health check (default: 30 seconds)auto_reconnect_enabled: Whether to automatically attempt reconnection (default: True)max_reconnect_attempts: Maximum number of reconnection attempts (default: 3)reconnect_delay: Delay between reconnection attempts (default: 2 seconds)
Benefits
- Stable Connections: Significantly reduces unexpected disconnections
- Automatic Recovery: No manual intervention needed when connections drop
- Better Reliability: Especially important for the critical
send_g1_messagecommand - Configurable: Adjust settings based on your specific use case and device behavior
Example Files
example_connect.py- Demonstrates device connectionexample_scan.py- Shows device scanning functionalityexample_send_message.py- Example of sending messagesexample_tools.py- Comprehensive tool usage examples- 🆕
test_connection_monitoring.py- Demonstrates the new connection monitoring features
Architecture
Core Components
mcp_server.py: Main MCP server implementation with tool definitions and connection configurationg1_uart_manager.py: Enhanced BLE UART protocol manager with connection monitoring and auto-reconnectionmcp.json: MCP server configuration
BLE UART Protocol
The server implements the Nordic UART service:
- Service UUID:
6E400001-B5A3-F393-E0A9-E50E24DCCA9E - TX Characteristic:
6E400002-B5A3-F393-E0A9-E50E24DCCA9E(Write) - RX Characteristic:
6E400003-B5A3-F393-E0A9-E50E24DCCA9E(Notify)
Dependencies
mcp: Model Context Protocol implementationbleak: Cross-platform Bluetooth Low Energy library
Troubleshooting
Common Issues
- Permission Denied: Ensure Bluetooth permissions are granted to your application
- Device Not Found: Verify the device is in range and discoverable
- Connection Failed: Check if the device is already connected to another client
- Message Timeout: Ensure the device is responsive and supports the Nordic UART protocol
- 🆕 Frequent Disconnections: Try adjusting connection monitoring settings or check device power management
Debug Mode
Enable debug logging by modifying the logging level in mcp_server.py:
logging.basicConfig(level=logging.DEBUG)
Connection Issues
If you're experiencing frequent disconnections:
-
Check connection monitoring settings:
status = get_g1_connection_status() print(f"Auto-reconnect: {status['auto_reconnect_enabled']}") print(f"Reconnect attempts: {status['reconnect_attempts']}") -
Adjust heartbeat frequency:
configure_g1_connection_settings(heartbeat_interval=3.0) -
Increase reconnection attempts:
configure_g1_connection_settings(max_reconnect_attempts=5) -
Check device power settings: Some devices may go to sleep mode, causing disconnections
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
[Add your license information here]
Support
For issues and questions, please create an issue or contact the maintainers.