COLMI Smart Ring Toolkit & Cross-Platform MCP Server

The definitive open-source toolkit, reverse-engineered Bluetooth Low Energy (BLE) protocol specification, and Model Context Protocol (MCP) server for COLMI R02, COLMI R03, and compatible smart rings. Connect physical health rings directly to AI agents (Claude Desktop, Cursor, Antigravity, VS Code) without vendor clouds, accounts, or subscriptions.

🔍 Search Keywords & Supported Hardware

Supported Devices:

• COLMI R02 & COLMI R03 Smart Rings

• COLMI R01, R04, R05, R06, R07, R08, R10 family

• QRing OEM Variants: KSIX Ring, boAt Ring, Blaupunkt, VK-5098, MERLIN, Hello Ring, RING1, TR-R02, OneRing, BOK.

• SoC Families: BlueX Micro RF03 / RF03-01 (ARM Cortex-M0) & Realtek RTL8762E / RTL8762ESF (ARM Cortex-M4F, RT02R revision).

Comparative Ecosystem:

• Oura Ring (Gen 2, Gen 3, Ring 4)

• Ultrahuman Ring AIR

• RingConn (Gen 1 & Gen 2)

• Samsung Galaxy Ring

Tags & Topic Index: colmi, colmi-r02, colmi-r03, smart-ring, oura-alternative, mcp-server, model-context-protocol, claude-desktop, cursor-ai, antigravity, bluetooth-le, ble, qring, reverse-engineering, local-first, biometrics, heart-rate-variability, hrv, sleep-staging, hypnogram, accelerometer, firmware.

Related MCP server: Oura MCP

🌐 Is it Cross-Platform?

YES, 100% Cross-Platform!

The toolkit and MCP server run natively on Linux, macOS, and Windows 10/11:

                       Cross-Platform Architecture
                       
                   ┌───────────────────────────────────┐
                   │    colmi-smart-ring MCP Server    │
                   └─────────────────┬─────────────────┘
                                     │
                                     ▼
                   ┌───────────────────────────────────┐
                   │   bleak Cross-Platform Engine     │
                   └─────────────────┬─────────────────┘
                                     │
         ┌───────────────────────────┼───────────────────────────┐
         ▼                           ▼                           ▼
 ┌───────────────┐           ┌───────────────┐           ┌───────────────┐
 │     Linux     │           │     macOS     │           │    Windows    │
 ├───────────────┤           ├───────────────┤           ├───────────────┤
 │ • BlueZ DBus  │           │ • Native Core │           │ • Windows.    │
 │ • Systemd /   │           │   Bluetooth   │           │   Devices.    │
 │   Raspberry Pi│           │ • Apple Silicon/│           │   Bluetooth   │
 │ • dbus-fast   │           │   Intel Mac   │           │   (WinRT BLE) │
 └───────────────┘           └───────────────┘           └───────────────┘

1. Bluetooth Layer (bleak): Automatically selects the native OS Bluetooth subsystem:

   • Linux: Speaks directly to the Linux BlueZ daemon via asynchronous DBus sockets.

   • macOS: Communicates through Apple's native CoreBluetooth framework on both Apple Silicon (M1/M2/M3/M4) and Intel Macs.

   • Windows: Interfaces with the native Windows.Devices.Bluetooth Universal Windows Runtime (WinRT) APIs.

2. MCP Protocol Layer (mcp 2.x): Operates over standard input/output (stdio), supported identically across all operating systems.

3. No External Cloud Dependencies: Communicates directly from your computer to the ring on your finger over local 2.4 GHz radio.

⚡ Feature Overview

• 🤖 Model Context Protocol (MCP) Server: Exposes 8 native tools to AI agents (scan_rings, get_ring_status, blink_ring, sync_time, get_daily_activity, get_sleep_and_recovery, read_realtime_vitals, get_motion_sample).

• 🔋 Device Health & Battery: Real-time battery %, charging state, hardware revision (RY03_V3.0), firmware version (RY03_3.00.22).

• 💡 Physical Bidirectional Alerts: Let your AI assistant physically blink the optical LEDs on your ring (blink_ring) when code finishes compiling or tests pass.

• 💤 Sleep Staging & Hypnogram: Reads multi-night sleep data (Deep, REM, Light, Awake) via the Big Data channel (0xBC / ID 0x27).

• 📊 Insight Engine (Recovery Score 0–100): Computes clinical-grade Recovery Scores, sleep efficiency, and Resting Heart Rate Nadir timing locally.

• 🏃 Step & Activity Telemetry: Daily cumulative steps, estimated calories, and distance.

• 🎮 Raw 3-Axis Accelerometer (12-bit): Stream real-time motion at 25–350 Hz with pitch, roll, vector magnitude, and tap detection for gesture control or MIDI.

• 🔒 Zero Telemetry / 100% Privacy: No QRing app, no Chinese cloud servers, no account registration.

🚀 Quickstart Installation

1. Clone & Install

git clone https://github.com/orviwan/mcp-for-colmi-smartring.git
cd mcp-for-colmi-smartring

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

🤖 Configuring with AI Assistants (Claude Desktop / Cursor)

A. Claude Desktop

Edit 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

{
  "mcpServers": {
    "smart-ring": {
      "command": "/path/to/Colmi/.venv/bin/python",
      "args": ["/path/to/Colmi/tools/colmi_mcp.py"],
      "env": {
        "PYTHONPATH": "/path/to/Colmi",
        "COLMI_RING_ADDRESS": "31:31:43:30:A9:00"
      }
    }
  }
}

(Tip: If you omit COLMI_RING_ADDRESS, the server will automatically scan and bind to whichever ring is closest).

B. Cursor IDE

In Cursor Settings $\rightarrow$ Features $\rightarrow$ MCP Servers (or in .cursor/mcp.json):

{
  "mcpServers": {
    "smart-ring": {
      "command": "/path/to/Colmi/.venv/bin/python",
      "args": ["/path/to/Colmi/tools/colmi_mcp.py"],
      "env": {
        "PYTHONPATH": "/path/to/Colmi"
      }
    }
  }
}

🛠️ MCP Tools Reference (What the AI Can Do)

💻 Standalone Command-Line Tools

You can also run all tools directly from your terminal:

# 1. Scan for nearby rings
colmi-scanner
# (or: python tools/colmi_scanner.py)

# 2. Query status & battery
colmi-reader --address 31:31:43:30:A9:00 --info --battery --set-time

# 3. Blink finder LED
colmi-reader --address 31:31:43:30:A9:00 --blink

# 4. Stream real-time 3-axis motion & tap detector
colmi-accel --address 31:31:43:30:A9:00

# 5. Record accelerometer samples to CSV for ML/gesture training
colmi-accel --address 31:31:43:30:A9:00 --csv my_gesture.csv

# 6. Run the Biometric Insight & Recovery Scoring Engine (Demo Simulation)
colmi-insights --demo

📚 Deep-Dive Documentation Index

🧪 Automated Testing

The repository includes a comprehensive pytest test suite with 20 unit tests verifying packet framing, 8-bit checksum algorithms, 12-bit signed accelerometer math, sleep hypnogram decoders, and MCP tool registrations:

PYTHONPATH=. pytest -v tests/

🙏 Attributions & Prior Art

This project builds directly upon the reverse-engineering breakthroughs, packet logs, and hardware teardowns conducted by the open-source smart ring research community. We gratefully credit the following upstream projects and authors:

• Aaron Christophel (@atc1441): Reverse-engineering the BlueX Micro RF03 SoC, STK8321 accelerometer, VC30F optical sensor, SWD pinouts, and creating the FasterRawValuesMOD firmware patch and Web Bluetooth flasher (atc1441/ATC_RF03_Ring).

• Wesley Ellis (@tahnok): Developing the foundational Python BLE client, discovering the 16-byte packet structure and 8-bit checksum algorithm (tahnok/colmi_r02_client).

• Tony Smith (@smittytone): Discovering and reverse-engineering the Big Data GATT channel (DE5BF728...) for multi-night sleep hypnograms and 24-hour SpO2 max/min records (smittytone/RingCLI).

• Puxtril (@Puxtril): Documenting the complete QRing opcode catalog, device settings, and response schemas reverse-engineered from the COLMI R03 (Puxtril/colmi-docs).

• Nosh118 (@Nosh118): Discovering the Realtek RTL8762ESF / RT02R hardware revision, QRing DFU OTA transfer protocol, and motion-to-MIDI mapping (Nosh118/colmi-ring-tools).

• Robin O'JW (@robinojw): TypeScript implementation, modular BLE adapters, and test fixture references (robinojw/openring).

• Cyril Zakka, MD (@cyrilzakka): Native iOS companion app connecting COLMI rings to Apple HealthKit with 100% local privacy (cyrilzakka/Halo-iOS).

• CitizenOneX (@CitizenOneX): 12-bit accelerometer two's complement decoding and wave gesture detection (CitizenOneX/colmi_r0x_controller).

• Juan Perez (@perezjuanj): Research into RingConn Gen 2 BLE protocol (perezjuanj/OpenCircuit).

See ATTRIBUTIONS.md for full license notices and upstream project details.

📄 License

This project is licensed under the permissive MIT License — see the LICENSE file for details.