# BLEA

Lets an agent scan for BLE devices, walk GATT services, and read or write characteristics under explicit confirmation. Useful when you need to inspect real hardware instead of guessing from logs.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 12
- Author: Nitmi
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Nitmi/blea
- Updated: 2026-09-29
- HTML: https://affpapa.org/en/nevibecode/mcp/blea

## What it does

BLEA stands for Bluetooth Low Energy Automation. One runtime, `ble`, serves two surfaces: plain subcommands print deterministic JSON or JSONL for scripts and shells, while `ble mcp` launches a stdio MCP server exposing the same tools with managed BLE sessions. Alongside it comes a skill that spells out the workflow and the safety boundaries, plus an MCP declaration.

The covered loop is the usual one: confirm the OS grants Bluetooth access, locate the right device nearby, enumerate GATT services, keep raw bytes as evidence and compare captures across runs. Anything that changes state waits for permission — `pair` takes `--allow-pairing` and a device confirmation, `exchange` takes `--allow-write`. Offline work is supported too: `diff` compares two captures, `replay` re-runs a saved one.

Python 3.10 or newer is required, and the OS supplies Bluetooth through Bleak. Install the runtime from PyPI first, because the local MCP server looks for the `ble` executable on `PATH`. Device names only resolve when exactly one scanned device carries that name, so prefer the identifier from `scan` — on macOS that is normally a UUID, not a MAC address.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add blea -- uvx blea
```
uvx runs the command named after the package; if the README names another one, use uvx --from blea <command>

### Codex

**Platform CLI**
```bash
codex mcp add blea -- uvx blea
```
uvx runs the command named after the package; if the README names another one, use uvx --from blea <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "blea": {
            "command": "uvx",
            "args": [
                "blea"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from blea <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "blea": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "blea"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from blea <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add blea uvx blea
```
uvx runs the command named after the package; if the README names another one, use uvx --from blea <command>

## When to use it
- check whether the OS exposes Bluetooth to tools
- pick the right device out of a crowded scan
- enumerate GATT services and characteristics
- keep raw bytes and compare two captures
- read a characteristic before changing device state

## Example prompts
- Run `ble doctor --json` and tell me what it says about Bluetooth access.
- Scan for 8 seconds and list the devices you find.
- Diff `before.blea.jsonl` against `after.blea.jsonl` with `ble diff`.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md