Ble MCP Server

🚀 BLE MCP Server

A stateful Bluetooth Low Energy (BLE) Model Context Protocol (MCP) server for developer tooling and AI agents, enabling seamless interaction with BLE devices.

🚀 Quick Start

For Claude Code

pip install ble-mcp-server

# Register the MCP server with Claude Code (read-only by default)
claude mcp add ble -- ble_mcp

Then in Claude Code, try:

"Scan for nearby BLE devices and connect to the one whose name starts with Arduino."

The server is read-only by default. Writes and plugins can control real hardware and execute code, and are opt-in via environment variables. See Safety for details.

✨ Features

• Versatile Compatibility: Works out of the box with Claude Code, VS Code with Copilot, and any MCP-compatible runtime.
• Cross - platform Support: Utilizes bleak for cross - platform BLE on macOS, Windows, and Linux.
• Full BLE Capabilities: Enables agents to scan, connect, read, write, and subscribe to notifications on BLE devices.
• Protocol Specs and Plugins: Allows agents to understand device - specific commands and data formats, and use high - level device operations.

📦 Installation

Development Installation

# Editable install from repo root
pip install -e .

# Or with uv
uv pip install -e .

Adding to Different Environments

Add to Claude Code

# Minimal (read-only)
claude mcp add ble -- ble_mcp

# Or run as a module
claude mcp add ble -- python -m ble_mcp_server

# Enable writes
claude mcp add ble -e BLE_MCP_ALLOW_WRITES=true -- ble_mcp

# Enable writes with an allowlist of characteristic UUIDs
claude mcp add ble \
  -e BLE_MCP_ALLOW_WRITES=true \
  -e BLE_MCP_WRITE_ALLOWLIST="2a00,12345678-1234-1234-1234-123456789abc" \
  -- ble_mcp

# Enable all plugins
claude mcp add ble -e BLE_MCP_PLUGINS=all -- ble_mcp

# Enable specific plugins only
claude mcp add ble -e BLE_MCP_PLUGINS=sensortag,hello -- ble_mcp

# Debug logging
claude mcp add ble -e BLE_MCP_LOG_LEVEL=DEBUG -- ble_mcp

Add to VS Code / Copilot

Add to your project's .vscode/mcp.json (or create it):

{
  "servers": {
    "ble": {
      "type": "stdio",
      "command": "ble_mcp",
      "args": [],
      "env": {
        "BLE_MCP_ALLOW_WRITES": "true",
        "BLE_MCP_PLUGINS": "all"
      }
    }
  }
}

Adjust env to match your needs — remove BLE_MCP_ALLOW_WRITES for read - only mode, or set BLE_MCP_PLUGINS to specific plugin names.

Add to Cursor

Add to your project's .cursor/mcp.json (or create it). Cursor does not support dots in tool names, so BLE_MCP_TOOL_SEPARATOR must be set to _:

{
  "mcpServers": {
    "ble": {
      "command": "ble_mcp",
      "args": [],
      "env": {
        "BLE_MCP_ALLOW_WRITES": "true",
        "BLE_MCP_PLUGINS": "all",
        "BLE_MCP_TOOL_SEPARATOR": "_"
      }
    }
  }
}

💻 Usage Examples

Example Session

The repo includes a simulated BLE peripheral you can run on a second machine (e.g. a Raspberry Pi) to try things end - to - end — no real hardware needed. See examples/demo-device/ for setup.

"Scan for BLE devices and connect to DemoDevice. Read the battery level, then start a data collection."

The agent will:

1. Scan for nearby devices and find DemoDevice
2. Connect and discover its services
3. Check for a matching protocol spec — if one exists, attach it to understand the device's protocol
4. Check for a matching plugin — if one exists, use its shortcut tools
5. If no spec or plugin exists, explore the device using raw BLE tools, or ask you for guidance
6. Read the battery level, configure the data service, and start collection

The example includes a pre - built protocol spec and plugin — copy them into .ble_mcp/specs/ and .ble_mcp/plugins/ to skip the exploration phase, or let the agent create its own from scratch.

Try without an Agent

You can test the server interactively using the MCP Inspector — no Claude or other agent needed:

npx @modelcontextprotocol/inspector python -m ble_mcp_server

Open the URL with the auth token from the terminal output. The Inspector gives you a web UI to call any tool, see responses, and observe MCP notifications (like disconnect alerts) in real time.

📚 Documentation

Tools

See Concepts for how everything fits together, and the Tools Reference for detailed input/output schemas.

Protocol Specs

Specs are markdown files that describe a BLE device's protocol — services, characteristics, commands, and data formats. They live in .ble_mcp/specs/ and teach the agent what a device can do beyond raw UUIDs and bytes.

Without a spec, the agent can still discover services and read characteristics. With a spec, it knows what the values mean and what commands to send.

You can create specs by telling the agent about your device — paste a datasheet, describe the protocol, or just let it explore and document what it finds. The agent generates the spec file, registers it, and references it in future sessions. You can also write specs by hand.

See Concepts for details on spec format and how the agent uses them.

Plugins

Plugins add device - specific shortcut tools to the server. Instead of the agent composing raw read/write sequences, a plugin provides high - level operations like sensortag.read_temp or ota.upload_firmware.

The agent can also create plugins (with your approval). It explores a device, writes a plugin based on what it learns, and future sessions get shortcut tools — no manual coding required.

To enable plugins:

# Enable all plugins
claude mcp add ble -e BLE_MCP_PLUGINS=all -- ble_mcp

# Enable specific plugins only
claude mcp add ble -e BLE_MCP_PLUGINS=sensortag,ota -- ble_mcp

Editing an already - loaded plugin only requires ble.plugin.reload — no restart needed.

See Concepts for the plugin contract, metadata matching, and how specs and plugins work together.

Tracing

Every tool call is traced to .ble_mcp/traces/trace.jsonl and an in - memory ring buffer (last 2000 events). Tracing is on by default — set BLE_MCP_TRACE=0 to disable.

Event format

Two events per tool call:

{"ts":"2025-01-01T00:00:00.000Z","event":"tool_call_start","tool":"ble.read","args":{"connection_id":"c1","char_uuid":"2a00"},"connection_id":"c1"}
{"ts":"2025-01-01T00:00:00.050Z","event":"tool_call_end","tool":"ble.read","ok":true,"error_code":null,"duration_ms":50,"connection_id":"c1"}

• connection_id is extracted from args when present
• value_b64 and value_hex are stripped from traced args by default (enable with BLE_MCP_TRACE_PAYLOADS=1)

Inspecting the trace

Use ble.trace.status to check config and event count, and ble.trace.tail to retrieve recent events — no need to read the file directly.

Platform BLE Permissions

macOS

No special setup is needed for most cases. On macOS 12+, the Terminal app (or whichever terminal you use) must have Bluetooth permission. Go to System Settings > Privacy & Security > Bluetooth and ensure your terminal is listed and enabled. If running from an IDE, the IDE itself may need the permission.

Windows

Requires Windows 10 version 1709 (Fall Creators Update) or later. No extra drivers needed — bleak uses the native WinRT Bluetooth APIs. Just make sure Bluetooth is turned on in Settings.

Linux

Requires BlueZ 5.43+. Your user must have permission to access the D - Bus Bluetooth interface. The simplest approach:

# Add your user to the bluetooth group
sudo usermod -aG bluetooth $USER
# Then log out and back in

If you are running in a container or headless environment, ensure dbus and bluetoothd are running.

🔧 Technical Details

Architecture

• stdio MCP transport — no HTTP, no network ports
• Stateful — connections and subscriptions persist in memory
• Safe by default — writes gated by env flags + allowlist
• Agent - friendly — structured outputs, buffered notifications
• Graceful shutdown — disconnects all clients on exit

Known Limitations

• Real hardware is asynchronous; agent runtimes mostly aren't. Devices disconnect, notifications arrive out of band, and state changes while the agent is thinking. Most agent runtimes are optimized for clean request/response loops. The server bridges this with polling tools, buffered notification queues, and MCP log notifications for disconnects and incoming data — but MCP log notifications are client - dependent (they work in the MCP Inspector; Claude Code currently ignores them). The agent can always detect disconnects on the next tool call and poll for notifications explicitly — the log messages are a best - effort heads - up, not a guarantee.
• Single - client only. The server handles one MCP session at a time (stdio transport). Multi - client transports (HTTP/SSE) may be added later.

📄 License

This project is licensed under the MIT License — see LICENSE for details.

Acknowledgements

This project is built on top of the excellent bleak library for cross - platform BLE in Python.