Fastmcp Transport Ble
BLE Transport used in FastMCP client
Ask AI about Fastmcp Transport Ble
Powered by Claude · Grounded in docs
I know everything about Fastmcp Transport Ble. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
fastmcp-transport-ble
A Bluetooth Low Energy (BLE) client transport for FastMCP.
This project provides a ClientTransport implementation that connects to an MCP server over BLE using GATT writes (client → server) and notifications (server → client). It is intended for scenarios where you want to run an MCP server on a BLE-capable device (embedded board, mobile device, etc.) and interact with it from a Python FastMCP client.
Features
- FastMCP
ClientTransportimplementation for BLE (powered bybleak) - Device discovery by BLE address or by advertised service UUID (with optional name hint)
- JSON-RPC message framing over GATT to support payloads larger than a single characteristic write
- Small, testable core for framing/packetization logic
Requirements
- Python 3.10+
- A BLE peripheral that implements the expected GATT service and characteristics (see “BLE GATT Protocol”)
- Supported host platform for
bleak(macOS, Windows, Linux; details depend on your BLE adapter and OS)
Installation
python -m pip install fastmcp-transport-ble
Usage
Create a FastMCP client with the BLE transport:
import asyncio
from fastmcp import Client
from fastmcp_transport_ble import BleTransport
async def main() -> None:
transport = BleTransport(
address=None,
name_hint="MCP_Server_BLE",
scan_timeout_s=10.0,
)
async with Client(transport) as client:
tools = await client.list_tools()
print([t.name for t in tools])
if __name__ == "__main__":
asyncio.run(main())
Demo script
There is a minimal demo at:
examples/list_tools/list_tools.py
Run it directly:
python examples/list_tools/list_tools.py --help
python examples/list_tools/list_tools.py --name-hint MCP_Server_BLE
python examples/list_tools/list_tools.py --address AA:BB:CC:DD:EE:FF
Configuration
BleTransport supports:
target: aBleTargetobject (or use the convenience args below)address: connect to a specific device addressname_hint: substring match against device name (applies when scanning)service_uuid: service UUID used for scanning (defaults toSERVICE_UUID)rx_char_uuid: characteristic UUID for client writes (defaults toRX_CHAR_UUID)tx_char_uuid: characteristic UUID for server notifications (defaults toTX_CHAR_UUID)scan_timeout_s: BLE scan timeout (seconds)request_mtu: optional MTU request (best-effort; platform-dependent)write_with_response: whether to write with response (reliable, but may be slower)
BLE GATT Protocol
This transport expects the peripheral to expose:
- A primary service UUID (default
SERVICE_UUID) - An RX characteristic UUID (default
RX_CHAR_UUID) that the client writes to - A TX characteristic UUID (default
TX_CHAR_UUID) that the client subscribes to for notifications
Payloads are UTF-8 JSON strings. Messages are framed into packets with a 1-byte header:
- High 2 bits: packet type (
SINGLE,START,CONT,END) - Low 6 bits: sequence number (mod 64)
Packet formats:
SINGLE:[header][json-bytes...]START:[header][total_len:4 bytes big-endian][chunk...]CONT:[header][chunk...]END:[header][chunk...]
The maximum payload per packet is derived from the negotiated MTU (minus ATT overhead), with a safety floor and a hard cap.
Development
Run unit tests:
python -m unittest discover -s tests -p "test*.py"
Compatibility notes
- BLE MTU negotiation support varies across platforms and adapters; the transport treats MTU requests as best-effort.
- GATT write/notify throughput can be limited; consider using smaller payloads and fewer concurrent requests if you see timeouts.
Contributing
Issues and pull requests are welcome. Please include:
- OS and Python version
- BLE adapter details (if relevant)
- Peripheral firmware/protocol details (UUIDs, MTU, packet sizes)
License
No license has been specified yet. Add a license file before publishing if you want others to legally reuse and redistribute the project.
