ble-mcp-server

BLE MCP 服务

一款有状态的 Bluetooth Low Energy（BLE）Model Context Protocol（MCP）服务，适用于开发者工具和 AI Agent。 开箱即用，支持 Claude Code、搭配 Copilot 的 VS Code，以及任何兼容 MCP 的运行时。默认使用 stdio（无 HTTP，不开放端口），还可选用 SSE 和 Streamable HTTP 传输方式，支持远程访问和多会话使用。使用 bleak 实现 macOS、Windows 和 Linux 上的跨平台 BLE 功能。

**示例：**让 Claude Code 扫描附近的 BLE 设备、连接其中一台、读取特征，并从真实硬件接收通知流。

演示

7 分钟视频演示 — 扫描真实 BLE 设备、发现服务、读取数值，并将工作流转化为插件。

---

为什么要开发这个项目

你有一台 BLE 设备，想让 AI Agent 与它交互——扫描、连接、读取传感器、发送命令、传输数据流。这个服务让这一切成为可能。

它为任何兼容 MCP 的 Agent 提供一整套 BLE 工具：扫描、连接、读取、写入、订阅通知，还提供协议规范和设备插件，让 Agent 能够推理设备的高层行为，而不只是处理原始 UUID 和字节。

Agent 调用这些工具，获取结构化 JSON，然后推理下一步该做什么——每次执行 BLE 操作都无需人工介入。

Agent 可以用它做什么：

• 开发和调试 — 连接设备、探索服务、读取特征、测试命令，并通过对话诊断问题。你可以直接询问：“为什么这个传感器返回的都是 0？”
• 适配新硬件 — 正在构建 BLE 设备？添加协议规范，让 Agent 在你迭代设备时理解其命令和数据格式。
• 自动化测试 — 编写设备专用插件，提供高层操作（例如 device.start_stream、device.run_self_test），然后让 Agent 执行测试序列：启用传感器、采集样本、验证数值并报告结果。
• 探索 — 让 Agent 检查一台从未见过的设备。它会发现服务、探测特征，并从头构建协议文档。
• 构建 BLE 自动化 — 让 Agent 控制真实硬件完成实际任务：定时读取环境传感器、管理一组 BLE 信标，或根据条件触发执行器。

---

适用人群

• 嵌入式工程师 — 更快迭代 BLE 协议、通过对话调试、自动执行测试序列
• 爱好者和创客 — 无需编写样板代码即可探索 BLE 设备；让 Agent 帮助逆向分析简单协议
• QA 和测试工程师 — 使用插件工具构建可重复运行的 BLE 测试套件，并通过 CI 或 Agent 会话执行
• 支持和现场工程师 — 无需专用工具，即可交互式诊断 BLE 设备问题
• 研究人员 — 自动采集 BLE 传感器数据，系统地探索设备功能

---

快速开始（Claude Code）

pip install ble-mcp-server

# Register the MCP server with Claude Code (read-only by default)
claude mcp add ble -- ble_mcp

然后在 Claude Code 中尝试：

“扫描附近的 BLE 设备，并连接到名称以 Arduino 开头的设备。”

该服务默认只读。写入操作和插件可以控制真实硬件并执行代码，必须通过环境变量选择启用。详情请参阅安全性。

---

Agent 能做什么

连接后，Agent 即可使用完整的 BLE 功能：

• 扫描附近的设备，可选择按名称或服务 UUID 筛选
• 连接设备并发现其服务和特征
• 读取和写入特征值（写入需要设置 BLE_MCP_ALLOW_WRITES）
• 订阅通知并收集流式数据——单次事件、轮询或批量读取
• 附加协议规范以理解特定设备的命令和数据格式
• 使用插件执行高级设备操作（例如 sensortag.read_temp），而非直接进行原始读写
• 为新设备创建规范和插件，逐步积累可跨会话复用的知识

Agent 会自动处理多步骤流程。例如，“读取我的 SensorTag 的温度”可能涉及扫描、连接、发现服务、附加规范、启用传感器并读取数值——无需你逐一指定每个步骤。

概括来说：

原始 BLE → 协议规范 → 插件

你可以从原始 BLE 工具开始，随着设备协议逐渐明晰并变得可重复使用，再逐步使用更高层的功能。有关各部分如何协同工作，请参阅概念。

---

安装（开发环境）

# Editable install from repo root
pip install -e .

# Or with uv
uv pip install -e .

MCP 是一种协议——此服务适用于任何兼容 MCP 的客户端。以下是最常见客户端的设置说明。

添加到 Claude Code

# Minimal (read-only)
claude mcp add ble -- ble_mcp

# Or run as a module
claude mcp add ble -- python -m ble_mcp_server

# Enable writes
claude mcp add ble -e BLE_MCP_ALLOW_WRITES=true -- ble_mcp

# Enable writes with an allowlist of characteristic UUIDs
claude mcp add ble \
  -e BLE_MCP_ALLOW_WRITES=true \
  -e BLE_MCP_WRITE_ALLOWLIST="2a00,12345678-1234-1234-1234-123456789abc" \
  -- ble_mcp

# Enable all plugins
claude mcp add ble -e BLE_MCP_PLUGINS=all -- ble_mcp

# Enable specific plugins only
claude mcp add ble -e BLE_MCP_PLUGINS=sensortag,hello -- ble_mcp

# Debug logging
claude mcp add ble -e BLE_MCP_LOG_LEVEL=DEBUG -- ble_mcp

添加到 VS Code / Copilot

将以下内容添加到项目的 .vscode/mcp.json（或新建该文件）：

{
  "servers": {
    "ble": {
      "type": "stdio",
      "command": "ble_mcp",
      "args": [],
      "env": {
        "BLE_MCP_ALLOW_WRITES": "true",
        "BLE_MCP_PLUGINS": "all"
      }
    }
  }
}

根据需要调整 env——只读模式下，移除 BLE_MCP_ALLOW_WRITES；也可以将 BLE_MCP_PLUGINS 设置为特定插件名称。

添加到 Cursor

将以下内容添加到项目的 .cursor/mcp.json（或新建该文件）：

{
  "mcpServers": {
    "ble": {
      "command": "ble_mcp",
      "args": [],
      "env": {
        "BLE_MCP_ALLOW_WRITES": "true",
        "BLE_MCP_PLUGINS": "all"
      }
    }
  }
}

环境变量

变量	默认值	说明
BLE_MCP_ALLOW_WRITES	禁用	设置为 true、1 或 yes 以启用 ble.write。
BLE_MCP_WRITE_ALLOWLIST	空	以逗号分隔的可写特征 UUID 允许列表（仅在启用写入时检查）。
BLE_MCP_PLUGINS	禁用	插件策略：设置为 all 以允许所有插件，或设置为 name1,name2 以允许指定插件。未设置 = 禁用。
BLE_MCP_LOG_LEVEL	WARNING	Python 日志级别（DEBUG、INFO、WARNING、ERROR）。日志输出到 stderr。
BLE_MCP_TRACE	启用	对每次工具调用进行 JSONL 跟踪。设置为 0、false 或 no 可禁用。
BLE_MCP_TRACE_PAYLOADS	禁用	在跟踪的参数中包含 value_b64/value_hex（默认会移除）。
BLE_MCP_TRACE_MAX_BYTES	16384	截断前的最大载荷字符数（仅在启用 TRACE_PAYLOADS 时生效）。
BLE_MCP_TOOL_SEPARATOR	_	用于分隔工具名称各部分的字符。如果客户端支持工具名称中使用点号，请设置为 .。默认值已改为 _，因为大多数客户端（Cursor、Claude Desktop）不接受点号。
BLE_MCP_MAX_SESSIONS	1	最大并发 MCP 会话数（仅对 SSE 和 Streamable HTTP 传输有意义）。
BLE_MCP_MAX_CONNECTIONS	3	每个会话的最大活动 BLE 连接数。
BLE_MCP_MAX_SCANS	5	每个会话的最大活动扫描数。
BLE_MCP_MAX_SUBSCRIPTIONS_PER_CONN	10	每个连接的最大通知订阅数。
BLE_MCP_AUTH_TOKEN	未设置	HTTP 传输下 OAuth 授权页面的密码。除非使用 --no-auth，否则必须设置。stdio 传输下会忽略。

---

工具

查看概念，了解各部分如何协同工作；查看工具参考，了解详细的输入/输出架构。

类别	工具
BLE 核心	ble_scan_start、ble_scan_get_results、ble_scan_stop、ble_connect、ble_disconnect、ble_connection_status、ble_discover、ble_mtu、ble_read、ble_write、ble_read_descriptor、ble_write_descriptor、ble_subscribe、ble_unsubscribe、ble_wait_notification、ble_poll_notifications、ble_drain_notifications
自省	ble_connections_list、ble_subscriptions_list、ble_scans_list、ble_tasks_list、ble_tasks_cancel
协议规范	ble_spec_template、ble_spec_register、ble_spec_list、ble_spec_attach、ble_spec_get、ble_spec_read、ble_spec_search
跟踪	ble_trace_status、ble_trace_tail
插件	ble_plugin_template、ble_plugin_list、ble_plugin_reload、ble_plugin_load

---

协议规范

规范是描述 BLE 设备协议的 Markdown 文件，涵盖服务、特征、命令和数据格式。它们存储在 .ble_mcp/specs/ 中，帮助 Agent 了解设备除了原始 UUID 和字节之外还能做什么。

没有规范时，Agent 仍可发现服务并读取特征。有了规范，它就能理解这些值的含义，以及应发送哪些命令。

你可以向 Agent 介绍设备来创建规范——粘贴数据手册、描述协议，或让它自行探索并记录发现的内容。Agent 会生成规范文件、注册该文件，并在后续会话中引用它。你也可以手动编写规范。

查看概念，了解规范格式以及 Agent 如何使用规范。

---

插件

插件可为服务添加特定于设备的快捷工具。插件提供 sensortag.read_temp 或 ota.upload_firmware 等高级操作，让 Agent 无需自行组合原始读写序列。

Agent 还可以创建插件（需经你批准）。它会探索设备，根据学到的内容编写插件；之后的会话即可使用快捷工具，无需手动编写代码。

启用插件：

# Enable all plugins
claude mcp add ble -e BLE_MCP_PLUGINS=all -- ble_mcp

# Enable specific plugins only
claude mcp add ble -e BLE_MCP_PLUGINS=sensortag,ota -- ble_mcp

编辑已加载的插件只需运行 ble_plugin_reload，无需重启。

后台任务

插件可以启动后台 asyncio 任务以持续监控，例如定期扫描、循环收集数据等。插件模板中包含了此类模式的注释示例。

后台任务通过 state.register_task(name, task) 向服务注册，因此 Agent 可以看到这些任务：

• ble_tasks_list — 显示所有正在运行的后台任务及其状态
• ble_tasks_cancel — 按 ID 停止任务（用于处理失控任务的安全措施）

插件通知

插件可以通过 state.on_log_cb(level, message) 向客户端发送 MCP 日志通知。这样，插件便能主动向 Agent 提醒事件——例如设备接入、超过阈值或检测到异常——而无需等待工具调用。

查看概念，了解插件契约、元数据匹配，以及规范与插件如何协同工作。

---

跟踪

每次工具调用都会被跟踪并写入 .ble_mcp/traces/trace.jsonl 和内存环形缓冲区（最近 2000 个事件）。跟踪默认开启——设置 BLE_MCP_TRACE=0 可将其禁用。

事件格式

每次工具调用会产生两个事件：

{"ts":"2025-01-01T00:00:00.000Z","event":"tool_call_start","tool":"ble.read","args":{"connection_id":"c1","char_uuid":"2a00"},"connection_id":"c1"}
{"ts":"2025-01-01T00:00:00.050Z","event":"tool_call_end","tool":"ble.read","ok":true,"error_code":null,"duration_ms":50,"connection_id":"c1"}

• 存在 connection_id 时，会从参数中提取
• 默认会从跟踪的参数中剔除 value_b64 和 value_hex（设置 BLE_MCP_TRACE_PAYLOADS=1 可启用）

检查跟踪记录

使用 ble.trace.status 检查配置和事件数量，使用 ble.trace.tail 获取最近的事件——无需直接读取文件。

---

平台 BLE 权限

macOS

大多数情况下无需特殊设置。在 macOS 12 及更高版本中，Terminal 应用（或你使用的其他终端）必须获得 Bluetooth 权限。前往 System Settings > Privacy & Security > Bluetooth，确保终端已列出并启用。如果从 IDE 运行，IDE 本身可能也需要此权限。

Windows

需要 Windows 10 version 1709（Fall Creators Update）或更高版本。无需额外驱动——bleak 使用原生 WinRT Bluetooth API。只需确保已在“设置”中开启 Bluetooth。

Linux

需要 BlueZ 5.43+。你的用户必须拥有访问 D-Bus Bluetooth 接口的权限。最简单的方法：

# Add your user to the bluetooth group
sudo usermod -aG bluetooth $USER
# Then log out and back in

如果在容器或无头环境中运行，请确保 dbus 和 bluetoothd 正在运行。

---

示例会话

仓库中包含一个模拟 BLE 外围设备，你可以在第二台机器（例如 Raspberry Pi）上运行它，端到端地试用，无需真实硬件。设置方法请参阅 examples/demo-device/。

“扫描 BLE 设备并连接到 DemoDevice。读取电池电量，然后开始数据采集。”

Agent 将会：

1. 扫描附近设备并找到 DemoDevice
2. 连接并发现其服务
3. 检查是否有匹配的协议规范——如果有，则附加该规范以了解设备的协议
4. 检查是否有匹配的插件——如果有，则使用其快捷工具
5. 如果没有规范或插件，则使用原始 BLE 工具探索设备，或向你寻求指导
6. 读取电池电量，配置数据服务并开始采集

此示例包含预先构建的协议规范和插件——将它们复制到 .ble_mcp/specs/ 和 .ble_mcp/plugins/，即可跳过探索阶段；也可以让 Agent 从头开始创建。

---

无需 Agent 即可试用

你可以使用 MCP Inspector 交互式测试服务端——无需 Claude 或其他 Agent：

npx @modelcontextprotocol/inspector python -m ble_mcp_server

使用终端输出中的身份验证令牌打开该 URL。Inspector 提供了一个 Web 界面，可用于调用任意工具、查看响应，以及实时观察 MCP 通知（例如断开连接警报）。

---

传输方式

服务端支持三种 MCP 传输方式。stdio 是默认方式，也是大多数使用场景的推荐选择——无需配置，也不会暴露到网络。HTTP 传输方式适用于远程访问和多客户端场景。

传输方式	命令	会话数	使用场景
stdio（默认）	ble_mcp	单个	命令行工具、IDE 集成
SSE	ble_mcp --transport sse	多个	较旧的 MCP 客户端、基于 Web 的工具
Streamable HTTP	ble_mcp --transport streamable-http	多个	较新的 MCP 客户端、生产部署

HTTP 传输选项

# SSE on default port (OAuth enabled by default)
ble_mcp --transport sse

# Streamable HTTP on custom host/port
ble_mcp --transport streamable-http --host 0.0.0.0 --port 9000

# No auth (for local testing with MCP Inspector, etc.)
ble_mcp --transport streamable-http --no-auth

# Allow up to 3 concurrent sessions
BLE_MCP_MAX_SESSIONS=3 ble_mcp --transport streamable-http

对于 SSE，客户端通过 GET /sse 连接，并向 /messages/ 发送消息。对于 Streamable HTTP，端点为 /mcp。

**会话隔离：**每个 MCP 会话都有独立的 BLE 状态——连接、扫描和订阅不会在会话之间共享。两个会话可以独立扫描或连接同一设备（前提是 BLE 硬件和设备允许）。

身份验证

HTTP 传输要求设置 BLE_MCP_AUTH_TOKEN。此令牌用作 OAuth 2.0 授权页面的密码——客户端连接时，会执行标准 OAuth 流程，用户必须输入此密码才能批准访问。

# Set a password and start the server
BLE_MCP_AUTH_TOKEN=mysecret ble_mcp --transport streamable-http

OAuth 流程（由 Claude Desktop 和其他 MCP 客户端自动处理）：

1. 客户端在 /.well-known/oauth-authorization-server 发现服务的 OAuth 元数据
2. 客户端通过动态客户端注册（/register）注册自身
3. 用户会被重定向到授权页面，并在那里输入 BLE_MCP_AUTH_TOKEN 密码
4. 客户端使用授权码换取访问令牌／刷新令牌

所有 OAuth 状态（客户端、令牌）都存储在内存中，重启后会丢失——客户端只需重新进行身份验证。

Claude Desktop 设置（通过隧道远程连接）：

# Terminal 1: start the server
BLE_MCP_AUTH_TOKEN=mysecret ble_mcp --transport streamable-http --host 0.0.0.0

# Terminal 2: expose via cloudflared
cloudflared tunnel --url http://localhost:8000

在 Claude Desktop 中，添加远程 MCP 服务，并填写隧道 URL 加上 /mcp 路径（例如 https://abc123.trycloudflare.com/mcp）。Claude Desktop 会处理 OAuth 流程——按提示输入密码即可。

不启用身份验证（仅限本地测试）：

在本地使用 MCP Inspector 或类似工具测试时，可以完全禁用身份验证：

ble_mcp --transport streamable-http --no-auth

如果未设置 BLE_MCP_AUTH_TOKEN 或 --no-auth，服务将拒绝通过 HTTP 传输启动。

stdio 传输会忽略所有身份验证设置——它不需要身份验证，因为客户端会将服务作为子进程启动。

**注意：**HTTP 传输需要 uvicorn 和 starlette。它们已作为 mcp 包的传递依赖安装，但你也可以使用 pip install ble-mcp-server[http] 显式安装。

---

架构

• 多种传输方式——stdio（默认）、SSE 和 Streamable HTTP
• 会话隔离——每个 MCP 会话都有自己的 BLE 状态
• 有状态——连接和订阅会持久保存在内存中
• 默认安全——写入操作受环境变量标志和允许列表控制
• 适合 Agent 使用——结构化输出、缓冲通知
• 平稳关闭——退出时断开所有客户端

---

已知限制

• **真实硬件操作是异步的；Agent 运行时大多不是。**设备会断开连接，通知会在带外到达，状态也会在 Agent 思考时发生变化。大多数 Agent 运行时针对简洁的请求／响应循环进行了优化。服务通过轮询工具、缓冲通知队列以及针对断开连接、收到的数据和扫描结果的 MCP 日志通知来弥合这一差异——但 MCP 日志通知取决于客户端（它们在 MCP Inspector 中有效；Claude Code 和 Claude Desktop 目前会忽略这些通知）。Agent 始终可以在下次调用工具时检测到断开连接，并显式轮询通知——日志消息只是尽力提供的提示，并非保证。自定义 MCP 客户端（例如，直接使用 MCP SDK 的边缘 Agent）可以接收并处理这些通知。

• **stdio 是单会话传输。**stdio 传输一次只处理一个 MCP 会话。如需多会话使用，请切换到 SSE 或 Streamable HTTP 传输，并使用 --transport sse 或 --transport streamable-http。

---

安全

此服务将 AI Agent 连接到真实硬件。这正是它的用途——也意味着风险高于纯软件工具。

插件会执行任意代码。 启用插件后，Agent 可以在你的计算机上以完整的服务权限创建并运行 Python 代码。加载前请审查 Agent 生成的插件。使用 BLE_MCP_PLUGINS=name1,name2 仅允许特定插件，而不是 all。

写入会影响真实设备。 向错误的特征值写入错误数据可能会导致设备损坏、触发意外行为，或干扰其他已连接的系统。除非确有需要，否则请禁用写入。使用 BLE_MCP_WRITE_ALLOWLIST 限制可写入的特征值。

谨慎进行工具审批。 当 MCP 客户端提示你批准工具调用时，请考虑是仅允许一次，还是始终允许。“始终允许”虽然方便，但意味着 Agent 无需再次确认即可重复执行该操作。

本软件按“原样”提供，遵循 MIT 许可证。你需对 Agent 使用硬件的行为负责。

---

许可证

本项目遵循 MIT 许可证——详情请参阅 LICENSE。

致谢

本项目基于优秀的 bleak 库构建，用于在 Python 中实现跨平台 BLE。