Ble MCP Server

🚀 BLE MCP 服務器

這是一個有狀態的藍牙低功耗 (BLE) 模型上下文協議 (MCP) 服務器，專為開發工具和 AI 代理設計。它可直接與 Claude Code、帶有 Copilot 的 VS Code 以及任何兼容 MCP 的運行時配合使用。該服務器通過 標準輸入輸出（無 HTTP，無開放端口）進行通信，並使用 bleak 庫實現跨平臺 BLE 功能，支持 macOS、Windows 和 Linux 系統。

示例：讓 Claude Code 掃描附近的 BLE 設備，連接到其中一個，讀取特徵值，並從真實硬件接收通知流。

演示

7 分鐘視頻演示 — 掃描真實的 BLE 設備，發現服務，讀取值，並將流程提升為插件。

🚀 快速開始

快速啟動（Claude Code）

pip install ble-mcp-server

# 向 Claude Code 註冊 MCP 服務器（默認只讀）
claude mcp add ble -- ble_mcp

然後在 Claude Code 中嘗試：

"掃描附近的 BLE 設備，並連接到名稱以 Arduino 開頭的設備。"

服務器 默認只讀。寫入操作和插件可以控制真實硬件並執行代碼，可通過環境變量進行選擇啟用。詳情請參閱 安全說明。

✨ 主要特性

為何開發此項目

如果你有一個 BLE 設備，並且希望 AI 代理與之交互，如掃描、連接、讀取傳感器數據、發送命令、流式傳輸數據，那麼這個服務器就能實現這些功能。

它為任何兼容 MCP 的代理提供了一套完整的 BLE 工具，包括掃描、連接、讀取、寫入、訂閱通知等，同時還提供協議規範和設備插件，使代理能夠理解更高級別的設備行為，而不僅僅是原始的 UUID 和字節數據。

代理調用這些工具後，會得到結構化的 JSON 數據，並據此決定下一步操作，無需人工干預每個 BLE 操作。

代理可以利用它做什麼：

• 開發與調試：連接到設備，探索其服務，讀取特徵值，測試命令，並以對話方式診斷問題。例如，你可以詢問 “為什麼這個傳感器返回零值？”
• 迭代新硬件：正在開發 BLE 設備？添加協議規範，讓代理隨著設備的發展理解你的命令和數據格式。
• 自動化測試：編寫特定於設備的插件，暴露高級操作（如 device.start_stream、device.run_self_test），然後讓代理運行測試序列：啟用傳感器、收集樣本、驗證值、報告結果。
• 探索：讓代理指向一個你從未見過的設備。它會發現服務、探測特徵值，並從頭開始構建協議文檔。
• 構建 BLE 自動化：讓代理控制真實硬件完成實際任務，如按計劃讀取環境傳感器數據、管理一組 BLE 信標、根據條件觸發執行器。

適用人群

• 嵌入式工程師：更快地迭代 BLE 協議，進行對話式調試，實現自動化測試序列。
• 愛好者和創客：無需編寫樣板代碼即可探索 BLE 設備；讓代理幫助逆向工程簡單協議。
• QA 和測試工程師：使用插件工具構建可重複的 BLE 測試套件，並從 CI 或代理會話中運行它們。
• 支持和現場工程師：無需專業工具即可交互式診斷 BLE 設備問題。
• 研究人員：自動從 BLE 傳感器收集數據，系統地探索設備功能。

代理的功能

連接後，代理具備完整的 BLE 功能：

• 掃描：掃描附近的設備，可選擇按名稱或服務 UUID 進行過濾。
• 連接：連接到設備並發現其服務和特徵值。
• 讀寫：讀取和寫入特徵值（寫入操作需要 BLE_MCP_ALLOW_WRITES 權限）。
• 訂閱通知：訂閱通知並收集流式數據，支持單事件、輪詢或批量讀取。
• 附加協議規範：附加協議規範以理解特定設備的命令和數據格式。
• 使用插件：使用插件進行高級設備操作（如 sensortag.read_temp），而不是進行原始的讀寫操作。
• 創建規範和插件：為新設備創建規範和插件，在不同會話中積累可重複使用的知識。

代理可以自動處理多步驟流程。例如，“從我的 SensorTag 讀取溫度” 可能涉及掃描、連接、發現服務、附加規範、啟用傳感器和讀取值，而無需你指定每個步驟。

從高層次來看： 原始 BLE → 協議規範 → 插件

你可以從原始 BLE 工具開始，隨著對設備協議的理解和重複使用，逐步提升到更高層次。有關各部分如何協同工作的詳細信息，請參閱 概念。

📦 安裝指南

開發環境安裝

# 從倉庫根目錄進行可編輯安裝
pip install -e .

# 或者使用 uv
uv pip install -e .

MCP 是一種協議，此服務器可與任何兼容 MCP 的客戶端配合使用。以下是最常見客戶端的設置說明。

添加到 Claude Code

# 最小化安裝（只讀）
claude mcp add ble -- ble_mcp

# 或者作為模塊運行
claude mcp add ble -- python -m ble_mcp_server

# 啟用寫入操作
claude mcp add ble -e BLE_MCP_ALLOW_WRITES=true -- ble_mcp

# 啟用寫入操作並設置特徵 UUID 白名單
claude mcp add ble \
  -e BLE_MCP_ALLOW_WRITES=true \
  -e BLE_MCP_WRITE_ALLOWLIST="2a00,12345678-1234-1234-1234-123456789abc" \
  -- ble_mcp

# 啟用所有插件
claude mcp add ble -e BLE_MCP_PLUGINS=all -- ble_mcp

# 僅啟用特定插件
claude mcp add ble -e BLE_MCP_PLUGINS=sensortag,hello -- ble_mcp

# 啟用調試日誌
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 文件中（如果文件不存在則創建）。由於 Cursor 不支持工具名稱中包含點號，因此必須將 BLE_MCP_TOOL_SEPARATOR 設置為 _：

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

環境變量

💻 使用示例

基礎用法

示例會話： 倉庫中包含一個模擬的 BLE 外設，你可以在第二臺機器（如樹莓派）上運行它，進行端到端測試，無需真實硬件。設置方法請參閱 examples/demo-device/。

"掃描 BLE 設備並連接到 DemoDevice。讀取電池電量，然後開始數據收集。"

代理將執行以下操作：

1. 掃描附近的設備並找到 DemoDevice。
2. 連接並發現其服務。
3. 檢查是否有匹配的協議規範 — 如果存在，則附加該規範以理解設備協議。
4. 檢查是否有匹配的插件 — 如果存在，則使用其快捷工具。
5. 如果沒有規範或插件，則使用原始 BLE 工具探索設備，或向你尋求指導。
6. 讀取電池電量，配置數據服務，並開始收集數據。

該示例包含預構建的 協議規範 和 插件 — 將它們複製到 .ble_mcp/specs/ 和 .ble_mcp/plugins/ 中可跳過探索階段，也可以讓代理從頭開始創建自己的規範和插件。

高級用法

你可以在不使用代理的情況下，使用 MCP Inspector 交互式測試服務器：

npx @modelcontextprotocol/inspector python -m ble_mcp_server

打開終端輸出中帶有認證令牌的 URL。Inspector 提供一個 Web UI，可調用任何工具，查看響應，並即時觀察 MCP 通知（如斷開連接警報）。

📚 詳細文檔

工具

有關各部分如何協同工作的詳細信息，請參閱 概念，有關詳細的輸入輸出模式，請參閱 工具參考。

協議規範

協議規範是描述 BLE 設備協議的 Markdown 文件，包括服務、特徵值、命令和數據格式。它們存儲在 .ble_mcp/specs/ 目錄中，可幫助代理理解設備的功能，而不僅僅是原始的 UUID 和字節數據。

如果沒有規範，代理仍然可以發現服務並讀取特徵值。但有了規範，它就能理解這些值的含義並知道要發送的命令。

你可以通過向代理描述設備來創建規範，例如粘貼數據手冊、描述協議，或者讓代理自行探索並記錄它發現的內容。代理會生成規範文件，註冊它，並在後續會話中引用。你也可以手動編寫規範。

有關規範格式和代理如何使用它們的詳細信息，請參閱 概念。

插件

插件為服務器添加特定於設備的快捷工具。代理無需編寫原始的讀寫序列，插件可以提供高級操作，如 sensortag.read_temp 或 ota.upload_firmware。

代理還可以 創建 插件（需經你批准）。它會探索設備，根據所學內容編寫插件，後續會話即可使用這些快捷工具，無需手動編碼。

要啟用插件：

# 啟用所有插件
claude mcp add ble -e BLE_MCP_PLUGINS=all -- ble_mcp

# 僅啟用特定插件
claude mcp add ble -e BLE_MCP_PLUGINS=sensortag,ota -- ble_mcp

編輯已加載的插件只需使用 ble.plugin.reload，無需重啟服務器。

有關插件契約、元數據匹配以及規範和插件如何協同工作的詳細信息，請參閱 概念。

跟蹤

每個工具調用都會被跟蹤到 .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+ 系統中，終端應用程序（或你使用的任何終端）必須具有 藍牙 權限。轉到 系統設置 > 隱私與安全 > 藍牙，確保你的終端已列出並啟用。如果從 IDE 運行，IDE 本身可能也需要此權限。

Windows

需要 Windows 10 版本 1709（秋季創意者更新）或更高版本。無需額外驅動程序，bleak 使用原生 WinRT 藍牙 API。只需確保在設置中打開藍牙。

Linux

需要 BlueZ 5.43+ 版本。你的用戶必須有權限訪問 D-Bus 藍牙接口。最簡單的方法是：

# 將你的用戶添加到 bluetooth 組
sudo usermod -aG bluetooth $USER
# 然後註銷並重新登錄

如果你在容器或無頭環境中運行，請確保 dbus 和 bluetoothd 正在運行。

🔧 技術細節

架構

• 標準輸入輸出 MCP 傳輸：無 HTTP，無網絡端口。
• 有狀態：連接和訂閱信息保存在內存中。
• 默認安全：寫入操作由環境標誌和白名單控制。
• 對代理友好：結構化輸出，緩衝通知。
• 優雅關閉：退出時斷開所有客戶端連接。

已知限制

• 真實硬件是異步的，而代理運行時大多不是：設備可能會斷開連接，通知可能會異步到達，並且在代理思考時狀態可能會發生變化。大多數代理運行時針對乾淨的請求/響應循環進行了優化。服務器通過輪詢工具、緩衝通知隊列和 MCP 日誌通知（用於斷開連接和傳入數據）來解決這個問題，但 MCP 日誌通知依賴於客戶端（它們在 MCP Inspector 中有效；Claude Code 目前忽略它們）。代理始終可以在下次工具調用時檢測到斷開連接並顯式輪詢通知 — 日誌消息只是盡力提供的提醒，並非保證。
• 僅支持單客戶端：服務器一次處理一個 MCP 會話（標準輸入輸出傳輸）。後續可能會添加多客戶端傳輸（HTTP/SSE）功能。

📄 許可證

本項目採用 MIT 許可證 — 詳情請參閱 LICENSE。

致謝

本項目基於優秀的 bleak 庫構建，該庫用於 Python 中的跨平臺 BLE 功能。

⚠️ 安全說明

此服務器將 AI 代理連接到真實硬件。這既是其目的，也意味著風險比純軟件工具更高。

• 插件會執行任意代碼：啟用插件後，代理可以在你的機器上創建並運行具有完整服務器權限的 Python 代碼。在加載代理生成的插件之前，請仔細審查。使用 BLE_MCP_PLUGINS=name1,name2 僅允許特定插件，而不是 all。
• 寫入操作會影響真實設備：錯誤地寫入錯誤的特徵值可能會損壞設備、觸發意外行為或干擾其他連接的系統。除非需要，否則請保持寫入操作禁用。使用 BLE_MCP_WRITE_ALLOWLIST 限制可寫入的特徵值。
• 謹慎使用工具批准：當你的 MCP 客戶端提示你批准工具調用時，請考慮是允許一次還是始終允許。“始終允許” 很方便，但意味著代理可以在無需進一步確認的情況下重複該操作。

本軟件按 “原樣” 提供，遵循 MIT 許可證。你應對代理對硬件的操作負責。