AI 에이전트가 안전한 Bluetooth Low Energy 진단, GATT 서비스 검색 및 오프라인 증거 재생을 통한 보호된 자동화를 수행할 수 있도록 지원합니다.
다른 이름 Nitmi/blea
- 스타
- 13
- Tools
- —
- 다운로드, 30일
- 423
- 최신 버전
- 0.7.0
- 마지막 커밋
- 2026년 9월 29일
- 라이선스
- MIT
BLEA MCP란?
BLEA은(는) MCP server입니다. AI 에이전트가 안전한 Bluetooth Low Energy 진단, GATT 서비스 검색 및 오프라인 증거 재생을 통한 보호된 자동화를 수행할 수 있도록 지원합니다.
프로젝트 README에서 생성된 요약
BLEA MCP server 정보
BLEA는 로컬 MCP server를 통해 AI 에이전트가 Bluetooth Low Energy 하드웨어와 상호작용할 수 있는 특화된 인터페이스를 제공합니다. 결정론적 진단, GATT 서비스 검색 및 제어된 자동화가 필요한 개발자와 에이전트를 위해 설계되었습니다. 이 시스템은 공유 런타임으로 ble 실행 파일을 사용하며, mcp 명령을 사용하여 stdio MCP server로 시작할 수 있습니다.
사용자는 스캔, 검사 및 장치 프로빙을 위한 특정 도구를 사용하여 Bluetooth 세션을 관리할 수 있습니다. 이 서버는 상태 변경 시 명시적인 승인을 요구하고, 쓰기를 시도하기 전에 characteristic을 읽거나 구독하는 메커니즘을 제공하여 안전성을 강조합니다. 또한 로우 바이트(raw byte) 증거를 캡처하고 오프라인 분석을 수행하는 고급 기능도 포함되어 있습니다. 이를 통해 물리적인 Bluetooth 어댑터나 실시간 하드웨어 없이도 서로 다른 장치 상태를 비교하거나 캡처된 세션을 재생할 수 있습니다.
활용 사례
- 1GATT 서비스 검색에이전트가 근처의 Bluetooth 장치에서 사용 가능한 서비스와 characteristic을 식별할 수 있습니다.
- 2캡처된 데이터 재생AI 클라이언트가 이전에 기록된 증거를 사용하여 Bluetooth 상호작용을 시뮬레이션하고 오프라인에서 로직을 테스트할 수 있습니다.
- 3보호된 자동화 수행에이전트가 명시적인 확인을 받은 후에만 Bluetooth characteristic에 대한 쓰기 작업을 실행할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
BLEA MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 BLEA MCP 설치
$ claude mcp add blea -- uvx bleaCursor에 BLEA MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"blea": {
"command": "uvx",
"args": [
"blea"
]
}
}
}VS Code에 BLEA MCP 설치
.vscode/mcp.json
{
"servers": {
"blea": {
"type": "stdio",
"command": "uvx",
"args": [
"blea"
]
}
}
}VS Code CLI에 BLEA MCP 설치
$ code --add-mcp '{"name":"blea","type":"stdio","command":"uvx","args":["blea"]}'Claude Desktop에 BLEA MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"blea": {
"command": "uvx",
"args": [
"blea"
]
}
}
}Codex에 BLEA MCP 설치
$ codex mcp add blea -- uvx bleaCodex config.toml에 BLEA MCP 설치
~/.codex/config.toml
[mcp_servers.blea] command = "uvx" args = ["blea"]
Gemini CLI에 BLEA MCP 설치
$ gemini mcp add -s user blea uvx -- bleaGemini settings.json에 BLEA MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"blea": {
"command": "uvx",
"args": [
"blea"
]
}
}
}자동 검사
2026년 11월 13일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기BLEA
BLEA — Bluetooth Low Energy Automation — is a universal Agent Plugin for safe, deterministic BLE work. It gives AI agents a portable Skill, a machine-readable CLI, a local MCP server, guarded automation, and offline evidence capture, diff, and replay.
The project is designed for the BLE work agents repeatedly need: checking OS Bluetooth access, finding the right nearby device, discovering GATT services, preserving and comparing raw byte evidence, reading and subscribing before changing state, and making writes only after explicit authorization.
| Surface | Role |
|---|---|
| Agent Plugin 1.0.0 | Packages the portable identity, Skill, and MCP declaration. |
| Agent Skill | Teaches agents the BLE workflow, safety boundaries, and recovery rules. |
| CLI | Emits deterministic JSON/JSONL for scripts, terminals, and any agent with shell access. |
| MCP | Exposes the same runtime as local, structured tools with managed BLE sessions. |
The ble executable is the shared runtime. Regular subcommands use the CLI surface; ble mcp
starts the stdio MCP server. The MCP protocol is therefore a first-class interface, not a second
tool hidden inside an unrelated CLI product.
Install
BLEA requires Python 3.10 or newer. Bluetooth access is provided by the operating system through Bleak.
Quick install with an Agent prompt
Give this prompt to an Agent with shell access:
Read https://github.com/Nitmi/blea and follow its README to install BLEA for me.
For manual installation, use the detailed paths below.
Install the latest published Python runtime from PyPI:
uv tool install blea
ble --help
For Codex, install the public Git marketplace package after the runtime:
codex plugin marketplace add Nitmi/blea
codex plugin add blea@blea
To install only the portable Agent Skill with the Skills CLI:
npx skills add Nitmi/blea --skill ble
For OpenClaw, install the same portable Skill from its public ClawHub listing:
openclaw skills install @nitmi/blea
# Or use the registry CLI directly:
clawhub install @nitmi/blea
The Skill teaches the workflow and safety policy; it does not install the Python runtime. Install
blea from PyPI as shown above before asking an agent to access live Bluetooth hardware or start
the local MCP server. The source Skill is skills/ble/SKILL.md, and the
public ClawHub release is @nitmi/blea.
Start a new Agent task after installation. The marketplace package supplies the BLE Skill and MCP
declaration; it does not install the Python runtime or operating-system Bluetooth permissions. See
docs/installation.md for the release-tag, legacy 0.6.0 bridge, and update
procedure.
From a checkout, install the command runtime directly from the working tree:
uv tool install --editable .
ble --version
For repository development:
uv sync --extra dev
uv run ble --help
Standalone Windows release
Starting with 0.6.5, each release includes blea-<version>-windows-x86_64.zip with a
single-file ble.exe and a manifest binding its SHA-256, version, target, and source commit. Python
is not required at runtime. The tag workflow builds twice on one GitHub-hosted Windows runner,
rejects unequal ZIP hashes, runs ble --version and an adapter-free evidence replay, and creates
GitHub artifact provenance. It does not run doctor, scan, or access Bluetooth hardware.
Verify the archive before use:
gh attestation verify blea-0.7.0-windows-x86_64.zip `
--repo Nitmi/blea `
--source-ref refs/tags/v0.7.0 `
--signer-workflow Nitmi/blea/.github/workflows/binary-release.yml `
--deny-self-hosted-runners
Attestation proves repository build provenance; it is not Windows Authenticode signing and does not prove a Bluetooth adapter, peripheral, or firmware identity.
The Python runtime and Agent Plugin are two related installation units: PyPI installs the ble
executable, while an Agent Plugins 1.0.0 client loads this repository directory to discover
plugin.json, mcp.json, and skills/ble. Install the runtime first so the plugin's local stdio
MCP server can find ble on PATH. See docs/installation.md for source,
plugin, update, permissions, and verification paths.
CLI
ble doctor --json
ble scan --timeout 8 --json
ble inspect --device "id:AA:BB:CC:DD:EE:FF" --json
ble probe --device "id:AA:BB:CC:DD:EE:FF" --max-reads 16 --json
ble probe --device "id:AA:BB:CC:DD:EE:FF" --max-reads 16 --read-offset 16 --json
ble read --device "id:AA:BB:CC:DD:EE:FF" --characteristic 2a19 --json
ble pair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
--confirm-device "AA:BB:CC:DD:EE:FF" --timeout 60 --json
ble subscribe --device "id:AA:BB:CC:DD:EE:FF" --characteristic 2a37 --duration 15 --jsonl
ble observe --device "id:AA:BB:CC:DD:EE:FF" --duration 10 --jsonl
ble diff before.blea.jsonl after.blea.jsonl --json
ble replay capture.blea.jsonl inspect --json
ble replay capture.blea.jsonl read --characteristic 2a19 --json
ble exchange \
--device "id:AA:BB:CC:DD:EE:FF" \
--write-characteristic 12345678-1234-1234-1234-1234567890ab \
--notify-characteristic 87654321-4321-4321-4321-ba0987654321 \
--text ping --duration 5 --allow-write \
--confirm-device "AA:BB:CC:DD:EE:FF" --jsonl
Device names are accepted only when exactly one observed device has that name. Prefer the
platform identifier returned by scan; on macOS this is normally a UUID rather than a MAC address.
Every binary value includes length, hex, base64, and replacement-safe UTF-8 representations.
JSON errors use stable reasons and exit codes suitable for agent recovery.
probe is paginated. Follow next_read_offset until it is null. Page counts and
characteristic-level failures live under read_page; ok=true means the page executed, while
read_page.has_failures tells you whether any characteristic failed. Every result includes a small
profile_summary. The CLI includes the full GATT profile by default and supports
--no-include-profile; the MCP tool omits it by default to keep repeated pages compact.
Connection commands report timeout_scope=per_backend_operation. Their timeout applies separately
to discovery, connection, and each GATT operation, rather than bounding the total command time.
GATT entries include uuid_namespace. BLEA reports library descriptions only for canonical
Bluetooth Base UUIDs, avoiding false standard names inferred from the leading bytes of custom
128-bit UUIDs.
observe discovers notify/indicate characteristics and watches them over one connection for a
bounded duration. Omit --characteristic to select all event-capable traits, or repeat it for
explicit selection. The result separates subscription failures, cleanup failures, and notification
events; a quiet window is evidence only for that sample window.
Save a complete read-only evidence package after diagnosis:
ble capture \
--device "id:AA:BB:CC:DD:EE:FF" \
--output capture.blea.jsonl \
--max-reads 128 \
--observe-duration 10 \
--redact-identifiers \
--json
capture records the advertisement, normalized GATT profile, each readable-characteristic result,
bounded notifications, operation errors, and a validated final summary. It performs no writes,
pairing, or configuration changes and replaces the destination only after an atomic close. The
JSONL file is the authoritative artifact; the command's JSON result is a compact summary. The
Evidence Format v1 contract and deterministic validator live in
docs/evidence-format-v1.md.
Compare two complete evidence packages without a Bluetooth adapter or device:
ble diff before.blea.jsonl after.blea.jsonl --json
ble diff before.blea.jsonl after.blea.jsonl --fail-on-change --json
diff validates both Evidence Format v1 inputs, projects them into stable BLE semantics, and emits
sorted JSON Pointer changes. It ignores capture IDs, timestamps, runtime metadata, sampling
duration, and RSSI movement within 5 dBm by default. Use --strict-rssi for exact RSSI comparison.
Device identifiers must match unless an intentional cross-device comparison uses
--allow-different-devices. Binary payloads are atomic changes, so one changed value does not
produce separate Hex, Base64, and UTF-8 noise. A normal difference exits successfully;
--fail-on-change returns code 3 after printing the complete result for CI. The contract lives in
docs/diff-format-v1.md.
Replay a complete evidence package without a Bluetooth adapter or physical device:
ble replay capture.blea.jsonl inspect --json
ble replay capture.blea.jsonl probe --max-reads 32 --json
ble replay capture.blea.jsonl read --characteristic 2a19 --json
ble replay capture.blea.jsonl observe --duration 10 --jsonl
ble replay capture.blea.jsonl run examples/replay-read-only.yaml --json
Replay reconstructs advertisements, GATT, reads, captured failures, subscription outcomes, and
the notification timeline through the same read-only backend interfaces used for live devices.
The default --speed 0 mode is immediate and deterministic; place a positive --speed before the
operation to preserve recorded notification gaps at that multiplier. Missing observations return
the stable replay_miss reason instead of an invented value or success. Replay never accesses a
real adapter and never sends or simulates writes or exchanges. The full contract lives in
docs/replay-format-v1.md.
Pairing
Explicit OS pairing and unpairing are separate guarded, one-shot operations on Windows and Linux.
Both require a fresh exact id: selector, --allow-pairing, and --confirm-device equal to the
resolved identifier. Discovery defaults to 5 seconds (--scan-timeout), separately from the
60-second pairing per-operation timeout. Unpairing removes the OS bond and can disconnect
other clients, so close any active BLEA session first. Neither action is automatically retried, and
both return structured JSON results. macOS does not expose explicit pair/unpair through Bleak;
protected GATT access prompts for pairing through the OS instead. Replay remains read-only even when
the pairing flags are provided.
ble pair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
--confirm-device "AA:BB:CC:DD:EE:FF" --timeout 60 --json
ble unpair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
--confirm-device "AA:BB:CC:DD:EE:FF" --json
For a Windows device that requires a six-digit PIN, set a process-local environment variable and
pass its name with --pin-env. The PIN is not included in CLI arguments or BLEA's result fields.
For example, after setting BLEA_PAIR_PIN locally:
ble pair --device "id:AA:BB:CC:DD:EE:FF" --allow-pairing \
--confirm-device "AA:BB:CC:DD:EE:FF" --pin-env BLEA_PAIR_PIN --json
This path uses Windows custom pairing with ProvidePin and requires encryption and authentication.
It refreshes the OS bond state and reports paired_before, paired_after, pin_used, and
authentication_verified. An existing bond reports already_paired without claiming the supplied
PIN was tested. There is no protection-level fallback or automatic numeric-comparison acceptance.
Remove the environment variable after use. MCP ble_pair accepts the same PIN as pin; the MCP
host may retain tool arguments in its history even though BLEA omits the PIN from its result.
Without a PIN, pairing uses Bleak's platform behavior. The pinned Bleak 1.1.1 Windows backend only handles confirmation-only pairing; it does not collect a PIN. Linux uses the configured BlueZ pairing agent; BLEA's explicit PIN parameter is currently Windows-only. A successful generic pair/unpair result reports backend completion and does not independently attest the OS bond store. Unpairing removes the host bond; it does not prove the peripheral erased its own stored keys. The Windows PIN acceptance records the tested configuration.
Guarded writes
A write requires both --allow-write and an exact confirmation of the resolved identifier:
ble write \
--device "id:AA:BB:CC:DD:EE:FF" \
--characteristic 12345678-1234-1234-1234-1234567890ab \
--hex 01 \
--allow-write \
--confirm-device "AA:BB:CC:DD:EE:FF" \
--read-back \
--json
YAML writes and exchanges add two more guards: the workflow must enable writes and each state-changing
step must declare dangerous: true plus successful prerequisite steps. The policy must also carry an
exact confirm_device identifier. See examples/guarded-write.yaml and
examples/esp32-burst-exchange.yaml.
For protocols where a write triggers notifications, use exchange. It enables the notification
subscription before performing the guarded write, then collects events for a bounded duration.
The write and notify characteristics may be the same or different. This avoids the race created by
launching standalone session subscribe and write operations concurrently.
For repeatable checks, an exchange step can assert the exact notification count, UTF-8 or Hex
content, the final notification, and subscription cleanup. Run a guarded YAML workflow with the
independent invocation gate:
ble run examples/esp32-burst-exchange.yaml --allow-write --json
Replace the example's device identifier and confirmation with the exact value returned by a fresh scan before running it.
MCP and Agent Plugin
Start the local stdio server directly:
ble mcp
The MCP surface includes one-shot tools, the offline ble_diff comparator, the offline
ble_replay runner, and stateful session tools. Sessions let an agent connect
once, inspect, read, observe, subscribe, perform a guarded request/notification exchange or write,
and then disconnect. ble_exchange and ble_session_exchange atomically subscribe before writing.
ble_pair and ble_unpair provide the same exact-device pairing guards as the CLI; they are
one-shot operations, not actions on an existing GATT session.
ble_session_list exposes active leases and ble_session_close_all provides explicit recovery.
The server disconnects all sessions when the MCP client exits and reaps an inactive session after
120 seconds by default. Set BLEA_SESSION_IDLE_SECONDS to another positive duration, or 0 to
disable idle reaping while retaining shutdown cleanup.
Close a known session with ble_session_close. Reserve ble_session_close_all for recovering an
unknown session ID, a failed explicit close, or confirmed leaked state.
To expose the normal MCP BLE tools against one capture instead of hardware, launch a dedicated replay server:
ble replay capture.blea.jsonl mcp
Every replay-backed BLE operation result identifies the evidence and carries
replay.read_only=true. Even if a client invokes an existing write or exchange tool with
live-device authorization fields, the ReplayBackend rejects it.
This repository is itself an Agent Plugins 1.0.0 package:
blea/
├── plugin.json portable plugin identity
├── mcp.json portable local stdio MCP declaration
├── skills/ble/SKILL.md portable Agent Skill
├── .codex-plugin/plugin.json root ChatGPT/Codex package metadata
├── .mcp.json root ChatGPT/Codex MCP declaration
├── .agents/plugins/marketplace.json public Git marketplace catalog
└── plugins/blea/ installable Codex distribution mirror
The plugin configuration expects the ble executable to be installed on PATH. The portable
specification distributes Skill and MCP metadata; native Bluetooth runtime installation and OS
permissions remain platform responsibilities.
The repository also carries server.json, the official MCP Registry package
metadata for the PyPI distribution. It declares a local stdio server and the mcp package
argument; it does not advertise a hosted or remote BLE service. Releases publish this metadata to
the official MCP Registry with short-lived GitHub OIDC
credentials after the matching PyPI version succeeds. The namespace preserves the GitHub login's
canonical casing because Registry authorization and package ownership markers are case-sensitive.
The root Dockerfile is a registry sandbox for MCP protocol introspection and
adapter-free tools. It builds the version-aligned release checkout and starts ble mcp, which lets
release-candidate CI run before that version exists on PyPI. It does not claim that a container can
access the host's Bluetooth adapter; use the native host installation above for live BLE work.
The OpenAI Plugins Directory submission uses the portable Skill only. BLEA's MCP server stays local
because live BLE requires the user's native host and adapter; it is not represented as a public
remote MCP endpoint. Submission copy, limitations, starter prompts, and review cases are recorded
in docs/openai-plugin-submission.md.
The public Codex distribution is registered at the immutable Git ref shown in the install section
and installed with codex plugin add blea@blea. A pinned ref does not advance to another release
when a marketplace snapshot is refreshed. To change releases, remove the configured marketplace,
add it again at the new v<version> tag, reinstall the Plugin, and start a new Agent task. Do not
treat installing the Python package alone as installing the Agent Skill or MCP declaration.
Platform status
Windows 11 is hardware-verified with the ESP32-S3 BLEA test server, including discovery, GATT,
notifications, guarded exchange, capture, and replay. macOS and Linux currently pass the unit suite
and replay the same real-device evidence in CI, but their native Bluetooth adapter paths have not
been tested on physical hosts. Treat those two platforms as CI + replay verified; native BLE hardware unverified until a published acceptance report says otherwise.
See docs/platform-acceptance.md for the exact support tiers,
privacy requirements, hardware acceptance procedure, and current evidence matrix.
Development
uv sync --extra dev
uv run python scripts/sync_codex_plugin.py --check
uv run python scripts/check_agent_package.py
uv run ruff check .
uv run ruff format --check .
uv run pytest
uv build --clear --no-create-gitignore
uv run python scripts/check_distribution.py dist
Unit tests use a fake BLE backend and do not require nearby hardware. CI runs on Windows, macOS,
and Linux. Each CI job also runs examples/replay-read-only.yaml against the checked-in complete
evidence fixture, providing an end-to-end CLI and Workflow smoke test with no adapter.
The root .codex-plugin, .mcp.json, and skills paths are the Codex Plugin source of truth. After
changing them, run uv run python scripts/sync_codex_plugin.py; CI uses --check to reject drift.
The repository-local Agent package checker validates both Codex Plugin roots, their MCP declaration,
Skill metadata, and agents/openai.yaml without relying on a maintainer's personal Skill directory.
The distribution checker also rejects missing marketplace files in the sdist and Plugin metadata in
the Python wheel.
Real adapter support is tracked separately from CI; CI success is not a native hardware support claim.
Release history lives in CHANGELOG.md. Maintainers should follow
docs/releasing.md for artifact, Trusted Publishing, Plugin, and
post-publication gates.
Companion project
For serial, UART, COM-port, USB-to-TTL, and firmware-console workflows, see
baud-cli. It provides an agent-friendly baud CLI and
portable Skill with guarded YAML automation, structured output, and archived raw-byte evidence.
BLEA MCP 질문
BLEA MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add blea -- uvx blea를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
BLEA MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
실제 하드웨어 없이 BLE 워크플로우를 테스트할 수 있나요?
네, 이전에 캡처한 증거 패키지에서 advertisement, GATT, read 및 notification을 재구성하는 재생 기능을 사용할 수 있습니다.
BLEA를 설치하려면 무엇이 필요한가요?
BLEA는 Python 3.10 이상이 필요하며, 운영 체제의 Bluetooth 액세스를 위해 Bleak 라이브러리를 사용합니다.