ble

This BLE MCP server exposes a stateful, stdio-based interface to interact with Bluetooth Low Energy devices via an MCP-compatible agent. It leverages the bleak library for cross-platform BLE support and presents a structured set of tools for scanning, connecting, reading, writing, and subscribing to notifications, all through JSON over stdio. Agents can attach protocol specs, use plugins for high-level device operations, and build repeatable flows (e.g., read_temperature, read_humidity) without scripting each BLE operation manually. The server is designed to work out of the box with MCP runtimes like Claude Code and VS Code with Copilot, enabling conversational interaction with real hardware through BLE tools.

To use it, install the Python package, run the server in stdio mode, and configure your MCP client or editor to connect to the server. You can then issue commands such as scan for devices, connect to a device, discover services, read and write characteristics (when enabled), and subscribe to notifications. Plugins and protocol specs can be attached to guide the agent in interpreting device-specific data formats and workflows, making BLE device automation accessible to AI-driven agents without low-level BLE boilerplate.

Prerequisites:

• Python 3.11+ installed on your system
• Optional: virtual environment tooling (recommended)
• Internet access to install Python packages

Step-by-step installation:

1. Create and activate a virtual environment (optional but recommended)

   • On macOS/Linux:
     • python3 -m venv .venv
     • source .venv/bin/activate
   • On Windows:
     • python -m venv .venv
     • ..venv\Scripts\activate

2. Install the BLE MCP server package from PyPI

   • pip install ble-mcp-server

3. Verify installation and run the server in stdio mode

   • python -m ble_mcp_server

4. (Optional) Configure integration in your MCP client/editor (Claude Code, VS Code, Cursor) to connect via stdio using the ble_mcp_server entry point.

Notes:

• The server communicates over stdio by design; no HTTP ports are opened.
• You can enable writes, plugins, and tracing through environment variables as shown in the mcp_config example.

Tips and common considerations:

• Environment variables control capabilities: BLE_MCP_ALLOW_WRITES enables write operations; BLE_MCP_PLUGINS selects which plugins are active. Use them to tailor the capabilities exposed to the MCP client.
• The default behavior is read-only; enabling writes requires explicit config.
• If you integrate with Cursor or other MCP clients that disallow dots in tool names, adjust BLE_MCP_TOOL_SEPARATOR to an alternative separator (e.g., _).
• Logs go to stderr; set BLE_MCP_LOG_LEVEL to DEBUG for verbose output during development.
• When debugging, enabling BLE_MCP_TRACE and BLE_MCP_TRACE_PAYLOADS can help trace tool calls and payloads for troubleshooting.
• Plugins can expose high-level device actions (e.g., sensortag.read_temp) to simplify interactions with BLE devices.
• If you encounter BLE device connection issues, ensure the target device is accessible and that your platform has the necessary Bluetooth permissions (e.g., macOS Bluetooth access, Windows Bluetooth stack, Linux D-Bus permissions).
• For production deployments, consider creating a deterministic setup with a dedicated virtual environment and documented environment variable configurations.