G1 UART

You run an MCP server that talks to G1 devices over Bluetooth Low Energy using the Nordic UART protocol. It enables you to scan, connect, send messages, and automatically monitor and maintain stable BLE connections with auto-reconnect capabilities, making it easier to integrate G1 device communication into MCP-enabled assistants and tools.

How to use

Use this MCP server to discover nearby G1 devices, establish a BLE connection, and exchange hex-formatted messages with Nordic UART, while keeping the connection healthy and automatically reconnecting when needed. You can control the workflow through an MCP client by starting the server as either a remote HTTP-based MCP endpoint or a local stdio process and then invoking the available tools to scan, connect, send messages, and monitor status.

How to install

Prerequisites you need before running the server are Python 3.8 or newer, macOS (tested on darwin 24.3.0), Bluetooth Low Energy support, and access to G1 devices.

Option 1. Quick Start with uvx (Recommended) Run directly from the source without installation.

uvx --from git+https://github.com/danroblewis/g1_uart_mcp g1-device-mcp

Add the MCP configuration to your mcp.json to define the MCP server entry.

{
  "mcpServers": {
    "g1-device-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/danroblewis/g1_uart_mcp",
        "g1-device-mcp"
      ]
    }
  }
}

Option 2. Local Installation (clone, install, and run locally) Follow these steps to set up a local environment and run the server.

git clone <repository-url>
cd g1_uart_mcp
python3 -m venv venv
source venv/bin/activate  # On macOS/Linux
pip install -r requirements.txt

Start the server via MCP configuration or run it locally.

# Start via MCP (local) using the standard Python entrypoint
python mcp_server.py

Configuration examples

You can configure the MCP server to use either the quick start method or a local Python path, depending on how you prefer to run it.

{
  "mcpServers": {
    "g1-device-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/danroblewis/g1_uart_mcp",
        "g1-device-mcp"
      ]
    }
  }
}

Additional configuration (local path)

If you run locally, point to your Python environment and the server script.

{
  "mcpServers": {
    "g1-device-mcp": {
      "command": "/path/to/your/venv/bin/python",
      "args": [
        "/path/to/your/g1_uart_mcp/mcp_server.py"
      ]
    }
  }
}

Notes on dependencies and environment

This project relies on the MCP framework and the bleak library for BLE interactions.

Troubleshooting

Common issues include permission problems for Bluetooth access, device not being found, or connection failures. Ensure Bluetooth permissions are granted, the G1 device is in range and powered, and that the device supports the Nordic UART service.

Enable debug logging to help diagnose problems by configuring the logging level.

logging.basicConfig(level=logging.DEBUG)

Example files

The project includes example scripts to demonstrate connection, scanning, and message sending.

Available tools

scan_g1_devices

Scans for available G1 devices and returns a list with device information including name, ID, side (left/right), and signal strength.

connect_g1_device

Connects to a specific G1 device by its address or UUID.

get_g1_connection_status

Returns detailed information about the current connection including device details, UART service availability, and connection monitoring statistics.

send_g1_message

Sends a hex-formatted message to the connected device and waits for a response. Includes automatic connection health checks and reconnection attempts.

disconnect_g1_device

Disconnects from the currently connected device.

configure_g1_connection_settings

Configures connection monitoring and auto-reconnection parameters such as heartbeat interval, timeouts, and reconnection behavior.