lw-ble-mcp
Provides tools for interacting with Bluetooth Low Energy (BLE) devices, enabling AI agents to scan, connect, read/write GATT characteristics and descriptors, query MTU, and subscribe to notifications.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@lw-ble-mcp Scan for BLE devices named 'HP_RDTS_P' and connect to the first one"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
lw-ble-mcp — 轻量级蓝牙调试 MCP Server
lw-ble-mcp 是一个面向 AI Agent 的轻量级蓝牙低功耗(BLE)调试 MCP 服务器。基于 MCP Python SDK(FastMCP)与 bleak 构建,以 lw_ble_* 前缀提供 21 个工具:扫描、连接、GATT 读写、描述符访问、MTU 查询、通知订阅、一键设备侦查(lw_ble_dump)与引擎诊断(lw_ble_engine_status)。
核心特性:连接永不挂死(全部原生调用在专用 I/O 事件循环上运行,带硬超时)· 下划线工具名兼容广泛 MCP 客户端 · 分层测试体系(76 个用例,含真机回环验证)。
工具标识统一使用
lw_ble_前缀与下划线风格:lw(lightweight,轻量级)沿用嵌入式领域惯例(如 lwIP),ble明确标注协议为蓝牙低功耗。命名刻意保持独立命名空间,避免与常见ble_*工具名冲突。
lw-ble-mcp is a lightweight Bluetooth Low Energy (BLE) debug MCP server for AI agents. Built on the MCP Python SDK (FastMCP) and bleak, it exposes 21 tools under the lw_ble_* prefix: scan, connect, GATT read/write, descriptor access, MTU query, notification subscription, one-shot device recon (lw_ble_dump), and engine diagnostics (lw_ble_engine_status).
Key features: connect never hangs (all native calls run on a dedicated I/O event loop with hard timeouts) · underscore tool names for broad MCP-client compatibility · a layered test suite (76 cases, including real-hardware echo-loop verification).
设计要点
关注点 | 实现 |
连接边界保护 | 全部 bleak 调用跑在独立线程的专用事件循环上,外层用 |
客户端兼容性 | 工具名一律用下划线( |
错误可诊断 | 区分 |
依赖 | 使用最新的 bleak 3.x |
Related MCP server: blew BLE MCP
安装
方式一:PyPI 安装(推荐)
pip install lw-ble-mcp方式二:源码安装
pip install -r requirements.txt在 Cursor 中配置
编辑全局 C:\Users\Administrator\.cursor\mcp.json(PyPI 安装后可直接用命令名):
{
"mcpServers": {
"ble": {
"type": "stdio",
"command": "ble_mcp",
"args": []
}
}
}源码运行时把 command 改为你的 Python 路径、args 用模块方式:
{
"mcpServers": {
"ble": {
"type": "stdio",
"command": "D:/DevTools/Python/v314/python.exe",
"args": ["-m", "ble_mcp"]
}
}
}配置后重启 Cursor。
工具列表
扫描
工具 | 说明 |
| 启动后台扫描(支持 name_filter / service_uuid),返回 scan_id |
| 非阻塞获取扫描结果 |
| 提前停止扫描 |
| 列出所有扫描 |
连接
工具 | 说明 |
| 连接外设(带硬超时,不挂死),返回 connection_id |
| 断开连接 |
| 查询单个连接状态 |
| 列出所有连接 |
GATT 读写
工具 | 说明 |
| 枚举服务的特征/描述符 |
| 读 GATT 特征(返回 base64 + hex) |
| 写 GATT 特征(data_b64 或 data_hex) |
| 按句柄读 GATT 描述符 |
| 按句柄写 GATT 描述符 |
| 查询协商 MTU |
通知订阅
工具 | 说明 |
| 订阅/取消订阅通知 |
| 非阻塞拉取通知缓冲 |
| 阻塞等待下一条通知 |
| 列出订阅 |
设备侦查与引擎诊断
工具 | 说明 |
| 一键侦查:服务表 + 全部可读特征值 + MTU(单个调用完成设备摸底) |
| 引擎资源状态:连接/扫描/订阅计数、I/O 线程健康度 |
信号强度(RSSI)通过
lw_ble_scan/lw_ble_scan_poll返回的每个设备记录获取。不提供独立的 RSSI 工具,因为 Windows 的 WinRT API 不支持从已建立连接中读取 RSSI。
测试
测试体系(常规/边界/参数/连接/稳定性/压力)详见 tests/README.md。
pip install -r requirements-dev.txt
pytest # mock 测试(无需硬件)
pytest -m hw # 真机测试(需 HP_RDTS_P 在线)直接运行(冒烟测试)
python -m ble_mcpMCP stdio server 会等待 stdin 的协议消息。可用 npx @modelcontextprotocol/inspector python -m ble_mcp 进行图形化调试。
本地开发运行
python -m ble_mcp相关信息
项目 | 值 |
模块名 |
|
作者 | linzhiwei(zevonlin) |
邮箱 | |
日期 | 2026-08-10 |
PyPI | |
GitHub | |
项目主页 | |
版本 | v0.1.0 |
Available Tools
21 toolslw_ble_connectB
Open a GATT session with a peripheral, addressed by its MAC. Returns a connection_id on success. The operation is wrapped in an outer timeout so a stalled driver call cannot leave the client waiting forever.
Inputs: address (required), pair, timeout_s. Returns: object
lw_ble_connection_listB
Enumerate every session the server currently holds.
Inputs: no named parameters. Returns: object
lw_ble_connection_statusB
Report the liveness of a session and the peripheral's identity details.
Inputs: connection_id (required). Returns: object
lw_ble_disconnectB
Close and forget an existing GATT session given its connection_id.
Inputs: connection_id (required). Returns: object
lw_ble_discoverB
Walk the remote GATT database and dump its services, characteristics, and associated descriptors in one call.
Inputs: connection_id (required), timeout_s. Returns: object
lw_ble_dumpB
One-shot device recon: service table, every readable characteristic value, and the negotiated MTU in a single call. Characteristics that fail to read are reported in read_failures instead of aborting the whole dump.
Inputs: connection_id (required), timeout_s. Returns: object
lw_ble_engine_statusA
Report engine resource usage: live links, scans, notification streams, and whether the I/O bridge thread is healthy. Useful for diagnosing resource exhaustion in long-running sessions.
Inputs: no named parameters. Returns: object
lw_ble_mtuB
Show the MTU agreed for a session; the useful per-packet payload is MTU minus three bytes of ATT overhead.
Inputs: connection_id (required), timeout_s. Returns: object
lw_ble_poll_notificationsA
Drain whatever notifications are already queued, without waiting; an empty result means nothing has arrived yet. The dropped counter reports overflow that was shed while nobody was reading.
Inputs: connection_id (required), subscription_id (required), max_items. Returns: object
lw_ble_readC
Fetch a characteristic's contents; the reply carries them as base64, hex, and a plain byte count.
Inputs: char_uuid (required), connection_id (required), timeout_s. Returns: object
lw_ble_read_descriptorB
Read a descriptor's bytes by its attribute handle; handles come from lw_ble_discover.
Inputs: handle (required), connection_id (required), timeout_s. Returns: object
lw_ble_scanA
Kick off a passive BLE discovery sweep. The call returns a scan handle immediately; the sweep runs for up to timeout_s seconds (bounded 1–60) and then shuts itself down. Retrieve findings with lw_ble_scan_poll or abort early with lw_ble_scan_stop.
Inputs: timeout_s, name_filter, service_uuid. Returns: object
lw_ble_scan_listA
Show every discovery sweep the server knows about, finished or not.
Inputs: no named parameters. Returns: object
lw_ble_scan_pollC
Fetch everything a sweep has gathered so far, plus whether it is still running.
Inputs: scan_id (required). Returns: object
lw_ble_scan_stopB
End a sweep now and hand back everything it recorded before stopping.
Inputs: scan_id (required). Returns: object
lw_ble_subscribeB
Begin receiving notification events from a characteristic; returns a subscription_id that later calls use to manage the stream.
Inputs: char_uuid (required), connection_id (required), timeout_s. Returns: object
lw_ble_subscription_listA
Show every notification stream the server is currently holding.
Inputs: no named parameters. Returns: object
lw_ble_unsubscribeC
Stop a notification stream and release its buffered data.
Inputs: connection_id (required), subscription_id (required), timeout_s. Returns: object
lw_ble_wait_notificationB
Wait up to timeout_s for the next notification and return it, or null if nothing arrives within the window.
Inputs: connection_id (required), subscription_id (required), timeout_s. Returns: object
lw_ble_writeB
Send bytes to a characteristic. Encode the payload as base64 (data_b64) or hex (data_hex); with_response selects write-with-response vs. fire-and-forget.
Inputs: char_uuid (required), connection_id (required), data_b64, data_hex, +2 more. Returns: object
lw_ble_write_descriptorC
Store bytes into a descriptor addressed by handle; encode the payload as base64 or hex.
Inputs: handle (required), connection_id (required), data_b64, data_hex, +1 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools target a distinct resource+action (connect/disconnect, read/write, subscribe/unsubscribe), and the descriptions clearly separate similar-sounding pairs like scan_poll vs scan_list and poll_notifications vs wait_notification. The main soft spot is lw_ble_dump overlapping with lw_ble_discover + lw_ble_read, since dump bundles discovery and characteristic reads into one convenience call.
All tools share the lw_ble_ prefix and snake_case, with a predictable verb_noun pattern (scan_stop, read_descriptor, poll_notifications, subscription_list). A few names are noun-only or omit the verb (mtu, dump, engine_status, connection_status), which is a minor deviation from the otherwise consistent scheme.
At 21 tools this is on the heavier side, but the BLE domain legitimately spans scanning, connection management, GATT discovery, characteristic/descriptor I/O, notifications, and diagnostics, and each tool maps to a real operation. No tool looks like filler, though a couple (dump, engine_status) are arguably conveniences rather than primitives.
The surface covers the full BLE lifecycle: scan start/poll/stop/list, connect/disconnect/status/list, GATT discovery, characteristic read/write, descriptor read/write, notification subscribe/unsubscribe/poll/wait/list, MTU, plus dump and engine diagnostics. There are no obvious dead ends for typical central-role workflows.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server exposing the Backtest360 engine API as tools for AI agents.
AgentReady Tools is a searchable catalog of more than 250 APIs, MCP servers and developer tools that AI agents can use, each with agent-readiness checks (docs, auth, OpenAPI, MCP support). Search by task, get tool details and related tools, and read or share field notes from other agents in the Agent Community. Remote MCP endpoint: https://agentready-tools.com/mcp
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Related MCP Servers
- AlicenseBqualityCmaintenanceA comprehensive MCP server that exposes Frida's dynamic instrumentation toolkit to AI agents for process management, script injection, and memory operations. It provides over 50 tools to interact with local and mobile devices, enabling advanced capabilities like function hooking and memory analysis.55MIT
- AlicenseNot gradedqualityCmaintenanceBluetooth Low Energy (BLE) MCP server that allows AI agents to scan, connect to and communicated with BLE devices, as well as simulate BLE perhipherals.27BSD 2-Clause "Simplified"
- AlicenseAqualityDmaintenanceA stateful Bluetooth Low Energy (BLE) MCP server that enables AI agents to scan, connect, read/write characteristics, and subscribe to notifications on BLE devices.3573 PyPI19MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control Bluetooth audio devices via MCP tools, including battery status, connect/disconnect, find-my, and snoop decoding.MIT