iOS BLE-MCP Bridge

Control iPhone Bluetooth Low Energy (BLE) devices from any AI agent (Cursor, Claude Desktop, etc.) via a WebSocket bridge and the beacio Safari extension.

How It Works

AI Agent (PC)
  └─ MCP stdio ─► server.js
                    └─ WebSocket (wss) ─► bridge.js (HTTPS hub, port 3000)
                                            └─ WebSocket ─► iPhone Safari (index.html)
                                                              └─ beacio extension ─► BLE Radio

1. bridge.js — HTTPS + WebSocket hub running on your PC (port 3000). Serves the bridge webpage and relays messages between the AI client and your iPhone.
2. server.js — Lightweight MCP server connected to your AI editor via stdio. Forwards tool calls to the bridge hub.
3. public/index.html — The bridge webpage opened on your iPhone. Uses the beacio Safari extension to execute Web Bluetooth commands.

---

Features

• 🔵 Scan, connect, read and write BLE devices from your iPhone via AI
• 🔒 HTTPS with auto-generated self-signed cert (includes IP SAN for LAN access)
• 🎵 Silent AudioContext background keep-alive (page stays alive when Safari is backgrounded)
• 🔄 Auto WebSocket reconnect on foreground return
• 🔔 System Notification support (desktop browsers)
• 🛡️ Full error handling — no unhandled crashes

---

Prerequisites

• Node.js v18+ on your PC
• iPhone with beacio app installed and Safari extension enabled ("Always Allow on Every Website")
• PC and iPhone on the same network (Wi-Fi or Tailscale)

---

Getting Started

1. Install Dependencies

npm install

2. Start the Bridge Hub

npm start

On first run, it generates cert.pem / key.pem for HTTPS. The terminal will print all your local IP addresses:

======================================================
[BRIDGE] Hub Server listening on HTTPS port 3000
[BRIDGE] Open this URL in Safari on your iPhone:
   👉 https://192.168.1.100:3000
======================================================

3. Connect Your iPhone

1. Open Safari on your iPhone and navigate to the URL shown above.
2. Safari will warn about the self-signed certificate — tap "visit this website" at the bottom to proceed.
3. On the bridge webpage, verify:
   • Bridge Server (WS): Connected (Green)
   • Safari Extension: Active (beacio) (Green)
4. Tap Enable on the Background Keep-Alive row to keep the page alive when you switch apps.

---

Integrate with Your AI Editor

Antigravity / Cursor

Add to your MCP config (adjust the path to wherever you cloned this repo):

{
  "mcpServers": {
    "ble-bridge": {
      "command": "node",
      "args": ["/path/to/ble-mcp-bridge/server.js"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ble-bridge": {
      "command": "node",
      "args": ["/path/to/ble-mcp-bridge/server.js"]
    }
  }
}

---

Available MCP Tools

Tool	Description
get_bridge_status	Check if iPhone bridge is connected
scan_ble_devices	Scan for nearby BLE devices (triggers user approval on iPhone)
connect_ble_device	Connect to a paired device by ID
read_ble_characteristic	Read a GATT characteristic value (returns hex)
write_ble_characteristic	Write a hex value to a GATT characteristic

---

Example Prompts

Check if my iPhone bridge is connected.

Scan for nearby Bluetooth devices with the heart_rate service.

Connect to device <id> with services ['heart_rate'].

Read the battery level (service '180f', characteristic '2a19') from my connected device.

---

Notes

• AirPods / Apple devices: Cannot be connected via Web Bluetooth (iOS system restriction).
• Classic Bluetooth: Not supported. Only BLE (Low Energy) devices work.
• Scan requires user gesture: When scanning for a new device, you must tap the Approve button on the iPhone. Once connected, all read/write operations run silently in the background.
• Self-signed cert: Delete cert.pem / key.pem and restart bridge.js to regenerate with updated IP SANs if your network changes.

---

License

MIT