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).

设计要点

安装

方式一：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。

工具列表

扫描

连接

GATT 读写

通知订阅

设备侦查与引擎诊断

信号强度（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_mcp

MCP stdio server 会等待 stdin 的协议消息。可用 npx @modelcontextprotocol/inspector python -m ble_mcp 进行图形化调试。

本地开发运行

python -m ble_mcp

相关信息