蓝牙MCP工具

Installation

Build from source

git clone --recurse-submodules https://github.com/stass/blew.git
swift build -c release
cp .build/release/blew /usr/local/bin/blew

--recurse-submodules is required — the Bluetooth SIG name and characteristic databases are included as git submodules under Vendor/. The Swift build generates all data files automatically from the submodule data.

On first run, macOS will prompt for Bluetooth permission. Grant it in System Settings → Privacy & Security → Bluetooth.

---

Quick start

```sh

Example structured output

A ble_scan call returns:

{
  "type": "devices",
  "devices": [
    {
      "id": "A1B2C3D4-...",
      "name": "Heart Rate Sensor",
      "rssi": -55,
      "serviceUUIDs": ["180D"],
      "serviceDisplayNames": ["Heart Rate"]
    }
  ]
}

A ble_read call returns:

{
  "type": "readValue",
  "readValue": {
    "char": "2A19",
    "name": "Battery Level",
    "value": "85",
    "format": "uint8"
  }
}

---

Global options

These options apply to all commands and must be placed before the subcommand name:

% blew [global-options] <command> [command-options]

Device targeting options

Commands that connect to a device (scan, connect, gatt, read, write, sub, periph clone) accept these options to identify the target. Pass them after the subcommand name.

Use --id to target an explicit device, or combine selectors to let blew find a match automatically.

---

Full GATT server from a config file

% blew periph adv --config device.json

Config file with name override

% blew periph adv -n "Override Name" --config device.json

Example config files are provided in the [`Examples/`](Examples/) directory:

| File | Description |
|------|-------------|
| `health-thermometer.json` | Health Thermometer (`1809`) — indicate temperature measurement (2A1C), read temperature type (2A1D), read/write/notify measurement interval (2A21) |
| `environmental-sensing.json` | Environmental Sensing (`181A`) — read/notify temperature (2A6E), humidity (2A6F), and pressure (2A6D) |
| `blood-pressure.json` | Blood Pressure (`1810`) — indicate measurement (2A35), read feature flags (2A49) |
| `custom-sensor.json` | Fully custom vendor service with 128-bit UUIDs — read/notify value, read/write config register, write-only command endpoint |

**Output (text mode):**

[12:34:56] central A1B2C3D4 connected [12:34:56] read 2A19 (Battery Level) by A1B2C3D4 [12:34:57] subscribe 2A19 (Battery Level) by A1B2C3D4 [12:35:01] write 2A19 (Battery Level) by A1B2C3D4 <- 2a ^C Stopped advertising.

**Output (kv mode):**

#### `periph clone` — Clone a real device

Connects to a target device, discovers its full GATT tree, reads all readable characteristic values, disconnects, then starts advertising as a clone.

| Flag | Description |
|------|-------------|
| `-n, --name` | Target device name filter. |
| `-i, --id` | Target device identifier. |
| `-o, --save <file>` | Save the cloned GATT structure to a JSON config file for later reuse. |

**Clone scope:**
- Cloned: advertised name, service UUIDs, full GATT structure, initial characteristic values (for readable characteristics).
- Not cloned: manufacturer data, service data in ADV payload, ADV timing.

**Examples:**

#### REPL-only periph commands

In REPL and `exec` mode, `periph adv` and `periph clone` run in two phases. The startup phase (configure + start advertising) is synchronous and confirms the peripheral came up. Once advertising is confirmed, the event loop runs as a background task and the prompt is returned immediately. This makes `periph stop`, `periph set`, and `periph notify` usable in the same session:

| Command | Description |
|---------|-------------|
| `periph stop` | Stop advertising and cancel the background event task. |
| `periph set [-f <fmt>] <char> <val>` | Update a characteristic's stored value. |
| `periph notify [-f <fmt>] <char> <val>` | Update value and push a notification to all subscribers. |
| `periph status` | Show advertising state, service/characteristic counts, subscriber count. |

In `exec` mode the same non-blocking behaviour applies, enabling scripts like:

---

Agent configuration

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "blew": {
      "command": "/path/to/blew",
      "args": ["mcp"]
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "blew": {
      "command": "/path/to/blew",
      "args": ["mcp"]
    }
  }
}

Find a device in a crowded environment

% blew scan -n "Sensor" -S 180F -R -65 -t 10

blew -- BLE scanner and CLI tool for Mac OS X

Stop fumbling with GUI apps to debug Bluetooth Low Energy devices. blew gives you full BLE control from the macOS command line: scan the airwaves, drill into any device's GATT tree, read and write characteristics, stream live notifications, and even spin up a virtual peripheral that other devices can connect to.

<img src="img/scan.avif" alt="BLE scan" width="100%">

<img src="img/gatttree.avif" alt="GATT tree" width="49%"> <img src="img/uart.avif" alt="UART" width="49%">

stdout vs stderr