ble-mcp-server

BLE MCP Server

開発者向けツールと AI エージェント用の、状態を保持する Bluetooth Low Energy（BLE）Model Context Protocol（MCP）サーバーです。 Claude Code、Copilot を搭載した VS Code、およびあらゆる MCP 互換ランタイムですぐに使用できます。デフォルトでは stdio を使用し（HTTP なし、ポート開放なし）、リモートアクセスや複数セッションでの使用向けに、オプションで SSE と Streamable HTTP トランスポートも利用できます。bleak を使用し、macOS、Windows、Linux でクロスプラットフォームの BLE を実現します。

例： Claude Code に近くの BLE デバイスをスキャンさせ、デバイスに接続し、キャラクタリスティックを読み取り、実際のハードウェアから通知をストリーミングさせます。

デモ

7 分間の動画ウォークスルー — 実際の BLE デバイスのスキャン、サービスの検出、値の読み取り、ワークフローのプラグイン化を紹介します。

---

このプロジェクトの目的

BLE デバイスがあり、AI エージェントに操作させたいとします。スキャン、接続、読み取り、センサーの値の取得、コマンドの送信、データのストリーミングが可能です。このサーバーは、それを実現します。

MCP 互換エージェントに、スキャン、接続、読み取り、書き込み、通知の購読といった BLE ツール一式を提供します。さらに、プロトコル仕様とデバイスプラグインも備えているため、エージェントは生の UUID やバイト列だけでなく、より高次のデバイス動作についても推論できます。

エージェントはこれらのツールを呼び出して構造化 JSON を受け取り、次に何をすべきかを推論します。BLE 操作のたびに人が介入する必要はありません。

エージェントでできること：

• 開発とデバッグ — デバイスに接続し、サービスを調べ、キャラクタリスティックを読み取り、コマンドをテストし、会話形式で問題を診断できます。「このセンサーがゼロを返すのはなぜ？」と質問できます。
• 新しいハードウェアで反復開発 — BLE デバイスを開発中ですか？プロトコル仕様を追加すれば、コマンドやデータ形式を変更しながら、エージェントが内容を理解できるようになります。
• テストを自動化 — デバイス固有のプラグインを作成して、高レベルのアクション（例：device.start_stream、device.run_self_test）を公開し、エージェントにテストシーケンスを実行させます。センサーを有効にし、サンプルを収集し、値を検証して、結果を報告できます。
• 探索 — これまで見たことのないデバイスをエージェントに調べさせます。サービスを検出し、キャラクタリスティックを調査し、ゼロからプロトコルのドキュメントを作成します。
• BLE の自動化を構築 — 実際のタスクのために、エージェントが実際のハードウェアを制御します。環境センサーの定期的な値の読み取り、BLE ビーコン群の管理、条件に応じたアクチュエーターの起動などが可能です。

---

対象ユーザー

• 組み込みエンジニア — BLE プロトコルの反復開発を高速化し、会話形式でデバッグし、テストシーケンスを自動化できます
• 愛好家やメーカー — 定型コードを書かずに BLE デバイスを調べ、エージェントに簡単なプロトコルのリバースエンジニアリングを任せられます
• QA エンジニア、テストエンジニア — プラグインツールで再現可能な BLE テストスイートを構築し、CI やエージェントセッションから実行できます
• サポートエンジニア、フィールドエンジニア — 専門的なツールを使わずに、対話形式で 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 で始まるデバイスに接続してください。」

このサーバーはデフォルトで 読み取り専用 です。書き込みやプラグインを有効にすると、実際のハードウェアを制御したり、コードを実行したりできます。有効化は環境変数によるオプトイン方式です。詳しくは安全性をご覧ください。

---

エージェントでできること

接続すると、エージェントはBLEの全機能を利用できます。

• 近くのデバイスをスキャンします。名前またはサービスUUIDによるフィルターを任意で指定できます
• デバイスに接続し、そのサービスとキャラクタリスティックを検出します
• キャラクタリスティックの値を読み取り、書き込みます（書き込みにはBLE_MCP_ALLOW_WRITESが必要です）
• 通知を購読し、ストリーミングデータを収集します。単発イベント、ポーリング、または一括取得が可能です
• プロトコル仕様を添付して、デバイス固有のコマンドやデータ形式を理解します
• 生の読み取り／書き込みの代わりに、プラグインを使って高度なデバイス操作を行います（例：sensortag.read_temp）
• 新しいデバイス用の仕様やプラグインを作成し、セッションをまたいで再利用できる知識を蓄積します

エージェントは複数ステップの処理を自動で行います。たとえば、「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	disabled	true、1、またはyesに設定すると、ble.writeが有効になります。
BLE_MCP_WRITE_ALLOWLIST	empty	書き込み可能なキャラクタリスティックのUUID許可リストをカンマ区切りで指定します（書き込みが有効な場合にのみ確認されます）。
BLE_MCP_PLUGINS	disabled	プラグインのポリシーです。すべてを許可するにはall、特定のプラグインを許可するにはname1,name2を指定します。未設定の場合は無効です。
BLE_MCP_LOG_LEVEL	WARNING	Pythonのログレベル（DEBUG、INFO、WARNING、ERROR）です。ログはstderrに出力されます。
BLE_MCP_TRACE	enabled	すべてのツール呼び出しをJSONL形式でトレースします。無効にするには0、false、またはnoを設定します。
BLE_MCP_TRACE_PAYLOADS	disabled	トレース対象の引数に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	unset	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/ に保存され、デバイスで生の UUID やバイト列以外に何ができるかをエージェントに教えます。

仕様がなくても、エージェントはサービスを検出し、特性を読み取ることができます。仕様があれば、値の意味や送信すべきコマンドがわかります。

デバイスについてエージェントに伝えることで仕様を作成できます。データシートを貼り付けたり、プロトコルを説明したり、エージェントにデバイスを調べて見つけた内容を文書化させたりできます。エージェントは仕様ファイルを生成して登録し、以降のセッションで参照します。仕様は手動で作成することもできます。

仕様の形式やエージェントによる使用方法の詳細については、コンセプトをご覧ください。

---

プラグイン

プラグインを使うと、デバイス固有のショートカットツールをサーバーに追加できます。エージェントが生の読み取り／書き込みシーケンスを組み立てる代わりに、プラグインが sensortag.read_temp や ota.upload_firmware のような高水準の操作を提供します。

エージェントはプラグインを作成することもできます（承認が必要です）。デバイスを調べて、学んだ内容に基づいてプラグインを作成すると、以降のセッションでショートカットツールを使えるようになります。手動でのコーディングは不要です。

プラグインを有効にするには、次のようにします。

# 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) を通じてサーバーに登録され、エージェントから確認できます。

• ble_tasks_list — 実行中のすべてのバックグラウンドタスクとそのステータスを表示します
• ble_tasks_cancel — ID を指定してタスクを停止します（暴走タスクに備えた安全策です）

プラグインの通知

プラグインは state.on_log_cb(level, message) を通じて、MCP のログ通知をクライアントに送信できます。これにより、ツール呼び出しを待たずに、デバイスの到着、しきい値の超過、異常の検出といったイベントをエージェントに能動的に通知できます。

プラグインの契約、メタデータの照合、仕様とプラグインの連携については、コンセプトをご覧ください。

---

トレース

すべてのツール呼び出しは .ble_mcp/traces/trace.jsonl とインメモリのリングバッファ（直近 2000 件のイベント）に記録されます。トレースはデフォルトで有効です。無効にするには BLE_MCP_TRACE=0 を設定してください。

イベント形式

ツール呼び出しごとに2つのイベントが発生します。

{"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 を使用します。Settings で 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 周辺機器が含まれています。2台目のマシン（例：Raspberry Pi）で実行でき、実機は必要ありません。セットアップについては examples/demo-device/ を参照してください。

「BLE デバイスをスキャンして DemoDevice に接続してください。バッテリーレベルを読み取り、その後、データ収集を開始してください。」

エージェントは次の操作を行います。

1. 近くのデバイスをスキャンして DemoDevice を見つけます
2. 接続して、そのサービスを検出します
3. 一致するプロトコル仕様を確認します。一致するものがあれば、デバイスのプロトコルを理解するために適用します
4. 一致するプラグインを確認します。一致するものがあれば、そのショートカットツールを使用します
5. 仕様もプラグインもない場合は、BLE の生ツールを使ってデバイスを調べるか、ユーザーに案内を求めます
6. バッテリーレベルを読み取り、データサービスを設定して、収集を開始します

この例には、あらかじめ用意されたプロトコル仕様とプラグインが含まれています。これらを .ble_mcp/specs/ と .ble_mcp/plugins/ にコピーして探索段階を省略することも、エージェントに一から作成させることもできます。

---

エージェントなしで試す

MCP Inspector を使ってサーバーを対話的にテストできます。Claude やその他のエージェントは必要ありません。

npx @modelcontextprotocol/inspector python -m ble_mcp_server

ターミナル出力に表示された認証トークンを使って URL を開きます。Inspector では、ウェブ UI から任意のツールを呼び出し、応答を確認し、MCP 通知（切断アラートなど）をリアルタイムで監視できます。

---

トランスポート

このサーバーは3種類の MCP トランスポートに対応しています。stdio がデフォルトであり、ほとんどの用途におすすめです。設定不要で、ネットワークに公開されません。リモートアクセスや複数クライアントのシナリオでは、HTTP トランスポートを利用できます。

トランスポート	コマンド	セッション数	用途
stdio（デフォルト）	ble_mcp	1	CLI ツール、IDE 統合
SSE	ble_mcp --transport sse	複数	古い MCP クライアント、ウェブベースのツール
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 ハードウェアとデバイスが許可していれば、2つのセッションで同じデバイスを個別にスキャンしたり、接続したりできます。

認証

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 で、トンネルの URL に /mcp パスを追加してリモート 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 状態を保持します
• ステートフル — 接続とサブスクリプションはメモリ内に保持されます
• デフォルトで安全 — 書き込みは環境変数フラグと許可リストで制御されます
• エージェントに適した設計 — 構造化された出力、バッファリングされた通知
• 適切なシャットダウン — 終了時にすべてのクライアントを切断します

---

既知の制限事項

• 実際のハードウェアは非同期ですが、エージェントのランタイムの大半はそうではありません。 デバイスは切断され、通知は非同期で届き、エージェントが処理を考えている間にも状態が変化します。多くのエージェントのランタイムは、単純なリクエスト／レスポンスのループに最適化されています。サーバーは、ポーリング用ツール、バッファリングされた通知キュー、切断・受信データ・スキャン結果に関する MCP ログ通知によってこのギャップを埋めます。ただし、MCP ログ通知はクライアントに依存します（MCP Inspector では機能しますが、Claude Code と Claude Desktop は現在無視します）。エージェントは次のツール呼び出しで常に切断を検出でき、通知を明示的にポーリングすることもできます。ログメッセージは可能な範囲で事前に知らせるものであり、保証ではありません。カスタム MCP クライアント（例：MCP SDK を直接使用するエッジエージェント）は、これらの通知を受信して対応できます。

• stdio は単一セッションです。 stdio トランスポートが同時に処理できる MCP セッションは 1 つです。複数のセッションで使用する場合は、--transport sse または --transport streamable-http を指定して、SSE または Streamable HTTP トランスポートに切り替えてください。

---

安全性

このサーバーは、AI エージェントを実際のハードウェアに接続します。それがこのサーバーの目的であり、純粋なソフトウェアツールよりもリスクが高いことを意味します。

プラグインは任意のコードを実行します。 プラグインを有効にすると、エージェントはお使いのマシン上で、サーバーの全権限を使って Python コードを作成し、実行できます。エージェントが生成したプラグインは、読み込む前に確認してください。all ではなく BLE_MCP_PLUGINS=name1,name2 を使って、特定のプラグインのみを許可してください。

書き込みは実際のデバイスに影響します。 誤った特性への不適切な書き込みは、デバイスを使用不能にしたり、意図しない動作を引き起こしたり、ほかの接続中のシステムを妨害したりする可能性があります。必要な場合を除き、書き込みは無効にしてください。BLE_MCP_WRITE_ALLOWLIST を使って、書き込み可能な特性を制限してください。

ツールの承認は慎重に行ってください。 MCP クライアントにツール呼び出しの承認を求められたら、その都度許可するか、常に許可するかを検討してください。「常に許可」は便利ですが、エージェントが追加の確認なしにその操作を繰り返せることを意味します。

このソフトウェアは、MIT licenseに基づき、現状のまま提供されます。エージェントがお使いのハードウェアに対して行うことについては、お客様が責任を負います。

---

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE をご覧ください。

謝辞

このプロジェクトは、Python でクロスプラットフォームの BLE を実現する優れたライブラリ bleak を基盤としています。