BLE

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.

How to use

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.

How to install

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.

Additional notes and setup details

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.

Example session flow

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.

Troubleshooting tips

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.

Safety considerations

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.

License

This software is released under the MIT license. You are responsible for how the agent interacts with your hardware.

Available tools

ble.scan_start

Initiate a BLE scan for nearby devices.

ble.scan_get_results

Retrieve the results of the current scan.

ble.scan_stop

Stop an ongoing BLE scan.

ble.connect

Connect to a selected BLE device.

ble.disconnect

Disconnect from the connected device.

ble.connection_status

Query the status of the current connection.

ble.discover

Discover services and characteristics on a device.

ble.mtu

Query or negotiate MTU with the connected device.

ble.read

Read a characteristic value from the device.

ble.write

Write a value to a writable characteristic.

ble.read_descriptor

Read a descriptor value.

ble.write_descriptor

Write a descriptor value.

ble.subscribe

Subscribe to notifications for a characteristic.

ble.unsubscribe

Unsubscribe from notifications.

ble.wait_notification

Wait for the next notification.

ble.poll_notifications

Poll for available notifications.

ble.drain_notifications

Drain and return buffered notifications.

ble.connections.list

List active connections.

ble.subscriptions.list

List active subscriptions.

ble.scans.list

List past scans.

ble.spec.template

Create a new protocol spec template.

ble.spec.register

Register a new protocol spec.

ble.spec.list

List registered protocol specs.

ble.spec.attach

Attach a spec to a device session.

ble.spec.get

Retrieve a registered spec.

ble.spec.read

Read data described by a spec.

ble.spec.search

Search specs for matching capabilities.

ble.trace.status

Check tracing configuration and status.

ble.trace.tail

Retrieve recent trace events.

ble.plugin.template

Create a new plugin template.

ble.plugin.list

List loaded plugins.

ble.plugin.reload

Reload a plugin without restarting.

ble.plugin.load

Load a plugin into the server.