Ble MCP Server

🚀 BLE MCP サーバー

開発ツールやAIエージェント向けの、状態管理付きのBluetooth Low Energy (BLE) モデルコンテキストプロトコル (MCP) サーバーです。Claude Code、Copilot付きのVS Code、およびMCP互換のランタイムでそのまま使用できます。標準入出力 (stdio) を介して通信し（HTTPやオープンポートは不要）、macOS、Windows、LinuxでのクロスプラットフォームBLEにはbleakを使用しています。

例: 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デバイスを開発している場合、プロトコル仕様を添付することで、エージェントがコマンドとデータ形式を理解できるようになります。
• 自動テスト - デバイス固有のプラグインを作成して、高レベルのアクション（例：device.start_stream、device.run_self_test）を公開し、エージェントにテストシーケンスを実行させます。センサーを有効にし、サンプルを収集し、値を検証し、結果を報告します。
• 探索 - エージェントを未経験のデバイスに向けると、サービスを発見し、特性を調査し、プロトコルドキュメントを最初から構築します。
• 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": "_"
      }
    }
  }
}

環境変数

💻 使用例

基本的な使用法

# サーバーをインストールする
pip install ble-mcp-server

# Claude Codeに登録する
claude mcp add ble -- ble_mcp

# Claude CodeでBLEデバイスをスキャンし、接続する
"Scan for nearby BLE devices and connect to the one whose name starts with Arduino."

高度な使用法

# 書き込みを有効にする
claude mcp add ble -e BLE_MCP_ALLOW_WRITES=true -- ble_mcp

# 特定のプラグインを有効にする
claude mcp add ble -e BLE_MCP_PLUGINS=sensortag,ota -- ble_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 を設定すると無効になります。

イベント形式

ツール呼び出しごとに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以降では、ターミナルアプリ（または使用しているターミナル）にBluetoothの権限が必要です。システム設定 > プライバシーとセキュリティ > Bluetooth に移動し、ターミナルがリストに含まれていて有効になっていることを確認してください。IDEから実行する場合は、IDE自体に権限が必要な場合があります。

Windows

Windows 10バージョン1709（Fall Creators Update）以降が必要です。追加のドライバーは必要ありません。bleakはネイティブのWinRT Bluetooth APIを使用します。設定でBluetoothがオンになっていることを確認してください。

Linux

BlueZ 5.43以上が必要です。ユーザーにD-Bus Bluetoothインターフェースにアクセスする権限が必要です。最も簡単な方法は以下の通りです。

# ユーザーをbluetoothグループに追加する
sudo usermod -aG bluetooth $USER
# その後、ログアウトして再ログインする

コンテナまたはヘッドレス環境で実行している場合は、dbus と bluetoothd が実行されていることを確認してください。

サンプルセッション

リポジトリには、エンドツーエンドで試すために、別のマシン（例：Raspberry Pi）で実行できるシミュレートされたBLEペリフェラルが含まれています。実際のハードウェアは必要ありません。セットアップについては、examples/demo-device/ を参照してください。

"BLEデバイスをスキャンし、DemoDeviceに接続します。バッテリーレベルを読み取り、データ収集を開始します。"

エージェントは以下のように動作します。

1. 近くのデバイスをスキャンし、DemoDeviceを見つけます。
2. 接続し、サービスを発見します。
3. 一致するプロトコル仕様があるか確認し、存在する場合はデバイスのプロトコルを理解するために添付します。
4. 一致するプラグインがあるか確認し、存在する場合はそのショートカットツールを使用します。
5. 仕様またはプラグインが存在しない場合は、生のBLEツールを使用してデバイスを探索するか、あなたにガイダンスを求めます。
6. バッテリーレベルを読み取り、データサービスを構成し、収集を開始します。

この例には、事前に構築されたプロトコル仕様とプラグインが含まれています。これらを .ble_mcp/specs/ と .ble_mcp/plugins/ にコピーすると、探索フェーズをスキップできます。または、エージェントに最初から独自の仕様とプラグインを作成させることもできます。

エージェントなしで試す

MCPインスペクターを使用して、Claudeや他のエージェントなしでサーバーを対話的にテストすることができます。

npx @modelcontextprotocol/inspector python -m ble_mcp_server

ターミナル出力から認証トークン付きのURLを開きます。インスペクターには、任意のツールを呼び出し、応答を表示し、MCP通知（切断アラートなど）をリアルタイムで観察するためのWeb UIがあります。

🔧 技術詳細

• stdio MCPトランスポート - HTTPやネットワークポートを使用しません。
• 状態管理付き - 接続とサブスクリプションはメモリ内に保持されます。
• デフォルトで安全 - 書き込みは環境フラグと許可リストによって制御されます。
• エージェントに優しい - 構造化された出力とバッファリングされた通知を提供します。
• グレースフルシャットダウン - 終了時にすべてのクライアントを切断します。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSE を参照してください。

謝辞

このプロジェクトは、PythonでのクロスプラットフォームBLE用の優れたbleak ライブラリをベースに構築されています。