ble-fleet-mcp

An MCP server that lets an AI agent manage a fleet of constrained-connection devices — 10, 100, or 1000+ of them — without ever having to know or reason about how many the underlying radio can actually hold open at once.

BLE radios typically support somewhere between 3 and 7 simultaneous connections. Existing BLE-to-MCP bridges expose scan / connect / read / write / subscribe as direct tools and leave connection management to the agent. That breaks down the moment a task involves more devices than the radio can hold open: "check the temperature on all 40 sensors in the warehouse" turns into forty manual connect/read/disconnect cycles, with the agent doing the bookkeeping itself — wasted tokens, wasted latency, and a real failure mode when it gets the bookkeeping wrong.

ble-fleet-mcp hides all of that. The agent asks for fleet-level outcomes — "read all sensors", "set brightness on every light in Zone 2" — and the server handles connection pooling, scheduling, retries, and partial failures underneath, inside a hard concurrency cap it enforces itself.

Agent ──MCP──▶ fleet_read("warehouse", "temperature_c")
                       │
                       ▼
        [ scheduler batches 40 devices behind a 4-connection pool,
          retries failures with backoff, circuit-breaks the
          unresponsive ones, evicts idle connections to make room ]
                       │
                       ▼
        { "SIM:0001": 21.4, "SIM:0002": "unreachable", ... }

Safety

• Read-only by default. fleet_write refuses to run unless the server is started with FLEET_ALLOW_WRITES=1 — same posture as ble-mcp-server.

• Verify-after-write. Every write is followed by a readback; the result reports both acknowledged (the device accepted the write) and converged (the readback actually matches what was requested) rather than trusting the ack alone.

• Risk tiering. Devices registered as safety_critical (e.g. a lock, in a fleet that also has light bulbs) are excluded from fleet_write batches by default and reported as confirmation_required, unless their address is explicitly listed in confirm_addresses on that call. A bulk write to "everything in Zone 2" can never silently include a lock.

• Nothing is silently dropped. Every device in a fleet operation resolves to success, a specific error (unreachable, timeout, write_rejected), or still_queued (pollable via fleet_operation_status) — never just missing.

• One bad device can't take down the fleet. Per-device timeouts and a circuit breaker isolate unresponsive devices; see docs/architecture.md.

Related MCP server: BLE MCP Server

Quick start

pip install ble-fleet-mcp

Or with uv:

uv add ble-fleet-mcp

Run it directly to sanity-check your BLE setup:

fleet-mcp

It speaks MCP over stdio, so in practice it's launched by your MCP client (see below), not run standalone. A minimal session, once connected from an agent:

fleet_register(name="warehouse", name_pattern="sensor")
  -> {"fleet": "warehouse", "device_count": 40, "addresses": [...]}

fleet_read(fleet="warehouse", resource="temperature_c")
  -> {"operation_id": "…", "status": "completed", "total": 40, "completed": 40,
      "results": {"AA:BB:...:01": {"status": "success", "value": 21.4}, ...}}

No BLE hardware handy? examples/simulated_fleet/ runs the exact same tool layer against a simulated fleet of virtual peripherals:

uv run python examples/simulated_fleet/demo.py --devices 50 --cap 4

Registering 50 simulated sensors (radio cap: 4)...
Reading temperature_c across the whole fleet...

Done in 1.64s over 50 devices with only 4 connections.
Status breakdown: {
  "success": 50
}

Adding it to your client

ble-fleet-mcp speaks standard MCP over stdio, so it works with any MCP-compatible client. Writes stay off unless you explicitly set FLEET_ALLOW_WRITES=1.

Claude Code

claude mcp add fleet-mcp -- fleet-mcp

Or add it to .mcp.json directly:

{
  "mcpServers": {
    "fleet-mcp": {
      "command": "fleet-mcp",
      "env": {
        "FLEET_MAX_CONNECTIONS": "4",
        "FLEET_ALLOW_WRITES": "0"
      }
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "fleet-mcp": {
      "command": "fleet-mcp",
      "env": {
        "FLEET_MAX_CONNECTIONS": "4",
        "FLEET_ALLOW_WRITES": "0"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "fleet-mcp": {
      "command": "fleet-mcp",
      "env": {
        "FLEET_MAX_CONNECTIONS": "4",
        "FLEET_ALLOW_WRITES": "0"
      }
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "fleet-mcp": {
      "type": "stdio",
      "command": "fleet-mcp",
      "env": {
        "FLEET_MAX_CONNECTIONS": "4",
        "FLEET_ALLOW_WRITES": "0"
      }
    }
  }
}

Tools

Full input/output schemas: docs/tools.md. Design rationale for the pool manager, scheduler, and circuit breaker: docs/architecture.md.

Environment variables

Web dashboard

A minimal, read-only dashboard over the same telemetry fleet_pool_status/fleet_status already expose: live connection pool gauges, per-device health, recent operations, and active watches. It's a stdlib http.server running in a background thread — no extra dependency, and it reads straight from the running server's in-memory state, so it's always exactly in sync.

Off by default. Enable it by setting FLEET_DASHBOARD_PORT:

FLEET_DASHBOARD_PORT=8765 fleet-mcp
# open http://127.0.0.1:8765

No hardware or MCP client needed to see it in action — examples/simulated_fleet/dashboard_demo.py runs the dashboard against a lively simulated fleet:

uv run python examples/simulated_fleet/dashboard_demo.py --devices 30 --cap 4
# open http://127.0.0.1:8765

Transports

The pool manager, scheduler, and MCP tool layer never import anything transport-specific — a new transport is a plugin, not a rewrite. See CONTRIBUTING.md.

Roadmap (not blocking 1.0.0)

• A second transport plugin (Zigbee or Thread) to prove the plugin interface generalizes beyond BLE.

• A "fleet template" registry for shareable configs of common device populations.

Development

git clone https://github.com/JephinJose/ble-fleet-mcp.git
cd ble-fleet-mcp
uv sync --extra dev
uv run pre-commit install
uv run pytest tests/unit

See CONTRIBUTING.md for the full workflow and how to add a transport plugin.

License

MIT — see LICENSE.