Provides tools for communicating with G1 devices over Bluetooth Low Energy using the Nordic UART protocol, enabling device discovery, connection management, and message exchange with paired left/right audio devices.
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:
For MCP Configuration:
Add this to your mcp.json
:
Option 2: Local Installation
- Clone the repository:
- Create a virtual environment:
- Install dependencies:
Configuration
The MCP server is configured via mcp.json
. For the recommended uvx method, use this configuration:
Alternative: Local Installation If you prefer local installation, update the paths to match your system:
Usage
Starting the MCP Server
The server can be started directly or through an MCP client:
With uvx (Recommended)
Local Installation
Available Tools
1. Scan for 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
Connects to a specific G1 device by its address or UUID.
3. Get Connection Status
Returns detailed information about the current connection including device details, UART service availability, and connection monitoring statistics.
4. Send Message
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
Disconnects from the currently connected device.
6. 🆕 Configure Connection Settings
Configures connection monitoring and auto-reconnection parameters.
Example Workflow
- Scan for devices:
- Connect to a device:
- Configure connection monitoring (optional):
- Send a message:
- Check status:
- Disconnect:
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_message
command - 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
:
Connection Issues
If you're experiencing frequent disconnections:
- Check connection monitoring settings:
- Adjust heartbeat frequency:
- Increase reconnection attempts:
- 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.
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables communication with G1 Bluetooth devices using the Nordic UART protocol over BLE. Supports device discovery, connection management, and message exchange for G1 audio devices through natural language commands.
Related MCP Servers
- -securityAlicense-qualityA ModelContextProtocol server that enables Claude AI to detect and scan nearby Bluetooth devices, providing Bluetooth sensing capabilities to Claude through a compatible MCP interface.Last updated -8PythonMIT License
- -securityFlicense-qualityAn integration that enables AI assistants to interact with network data through a standardized protocol, providing AI-ready tools and interfaces for network automation and management.Last updated -15Python
- AsecurityAlicenseAqualityA server implementation that enables natural language interactions with UniFi network devices by wrapping the UniFi Network API for AI agents like Goose and Claude.Last updated -2PythonMIT License
- -securityFlicense-qualityEnables seamless integration with Typecast API through the Model Context Protocol, allowing clients to manage voices, convert text to speech, and play audio in a standardized way.Last updated -2Python