Provides a stateful BLE MCP server to scan, connect, read, write, subscribe, and automate BLE devices through MCP clients.
Configuration
View docs{
"mcpServers": {
"es617-ble-mcp-server": {
"command": "python",
"args": [
"-m",
"ble_mcp_server"
],
"env": {
"BLE_MCP_TRACE": "true",
"BLE_MCP_PLUGINS": "all",
"BLE_MCP_LOG_LEVEL": "DEBUG",
"BLE_MCP_ALLOW_WRITES": "true",
"BLE_MCP_TRACE_PAYLOADS": "true",
"BLE_MCP_TRACE_MAX_BYTES": "16384",
"BLE_MCP_WRITE_ALLOWLIST": "2a00,12345678-1234-1234-1234-123456789abc"
}
}
}
}You can run a stateful BLE MCP server locally to let an MCP-compatible agent talk to Bluetooth Low Energy devices. It runs over stdio (no HTTP, no open ports) and leverages Bleak for cross‑platform BLE access, enabling you to scan, connect, read, write, subscribe to notifications, and work with device protocols and plugins in a structured, agent-friendly way.
You interact with the BLE MCP server through an MCP client. Start the server locally, then configure your client to connect via stdio. With the server running, you can: scan for nearby devices, connect to a chosen device, discover its services and characteristics, read and optionally write characteristic values, and subscribe to notifications. Attach protocol specs and plugins to enable high-level device operations, so the agent can reason about the device without handling raw UUIDs and bytes for every action.
In practice, you install the server, start it, and then point your MCP client to its stdio endpoint. The agent will perform multi-step flows automatically, such as scanning a device, attaching a spec if available, enabling sensors, and collecting data, all without you issuing every single command.
Prerequisites: Python installed on your system. Optionally, you may use the uv tool for development workflows. You will also need the MCP client you plan to use (for example Claude Code) to connect to this server.
Install the BLE MCP server package from the Python package index.
Optionally, install in editable mode from source if you are developing against the repository.
Environment variables Enable or restrict writes and control plugins using environment variables shown in the configuration table. The server starts in read-only mode by default; you opt-in to writes and plugin usage by setting the corresponding variables.
Platform permissions are required for BLE access on macOS, Windows, and Linux. Review the platform-specific notes to ensure your terminal or IDE has the necessary Bluetooth permissions, and whether you need to join the bluetooth group on Linux.
For troubleshooting, verify the server starts correctly, confirm the MCP client connects, and check trace and log output if you enable tracing. The server is designed to be safe by default and will only perform writes if you enable them and if the target characteristics are allowed.
1) Start the BLE MCP server locally. 2) From your MCP client, scan for nearby devices and connect to a device that matches your expected name or service UUIDs. 3) Attach a protocol spec if one exists for the device; otherwise, explore raw BLE tools to learn its behavior. 4) Read a sensor value, subscribe to a data service, or run a high-level plugin if available. 5) Save or export the discovered protocol and plugins to reuse in subsequent sessions.
If you encounter connection issues, verify that the BLE adapter is powered on and that the agent has permission to access BLE services. Check that the MCP client is configured to connect via stdio and that your environment variables match the intended access controls. If a device disconnects unexpectedly, use polling and buffered notifications to recover state and resume data collection on the next tool call.
This server connects an AI agent to real hardware. Plugins can execute code on your machine, so review any plugin you load before enabling it. Keep writes disabled unless you explicitly need to control a device, and restrict writable characteristics with a allowlist. Use deliberate tool approvals to avoid unintended actions.
This software is released under the MIT license. You are responsible for how the agent interacts with your hardware.
Initiate a BLE scan for nearby devices.
Retrieve the results of the current scan.
Stop an ongoing BLE scan.
Connect to a selected BLE device.
Disconnect from the connected device.
Query the status of the current connection.
Discover services and characteristics on a device.
Query or negotiate MTU with the connected device.
Read a characteristic value from the device.
Write a value to a writable characteristic.
Read a descriptor value.
Write a descriptor value.
Subscribe to notifications for a characteristic.
Unsubscribe from notifications.
Wait for the next notification.
Poll for available notifications.
Drain and return buffered notifications.
List active connections.
List active subscriptions.
List past scans.
Create a new protocol spec template.
Register a new protocol spec.
List registered protocol specs.
Attach a spec to a device session.
Retrieve a registered spec.
Read data described by a spec.
Search specs for matching capabilities.
Check tracing configuration and status.
Retrieve recent trace events.
Create a new plugin template.
List loaded plugins.
Reload a plugin without restarting.
Load a plugin into the server.