# ble-mcp-server Hands an agent the tools to scan for BLE devices, connect, read and write characteristics, and subscribe to notifications. Useful when you debug firmware or pull sensor data without doing every step by hand. - MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 18 - Author: es617 - License: MIT · policy=link-only · description only; the file stays with the author - Source: https://github.com/es617/ble-mcp-server - Updated: 2026-03-30 - HTML: https://affpapa.org/en/nevibecode/mcp/ble-mcp-server ## What it does Under the hood it uses `bleak`, so Bluetooth Low Energy works on macOS, Windows and Linux alike. The default transport is stdio: no HTTP, no listening ports. SSE and Streamable HTTP are available too, for remote access or when several sessions share one server. The agent gets a toolset and chains the calls itself: it finds a device by name or service UUID, connects, walks the services and characteristics, then reads values. Incoming notifications arrive as single events, by polling, or drained in batches. Everything comes back as structured JSON, and the model picks the next step from there. Writes stay off until you set `BLE_MCP_ALLOW_WRITES`. To narrow them down, put the allowed UUIDs in `BLE_MCP_WRITE_ALLOWLIST` so `ble.write` touches only those. Device plugins are opt-in as well through `BLE_MCP_PLUGINS`; they give the agent named actions instead of raw bytes. ## Requirements - Needs: Python and uv (commands run via uvx) - Environment variables: `BLE_MCP_ALLOW_WRITES`, `BLE_MCP_WRITE_ALLOWLIST`, `BLE_MCP_PLUGINS`, `BLE_MCP_TOOL_SEPARATOR`, `BLE_MCP_MAX_SESSIONS`, `BLE_MCP_AUTH_TOKEN` — keys and tokens: ask the human for the values, never commit them or put them in shared files. ## Install ### Claude Code (native platform) **Platform CLI** ```bash claude mcp add --env BLE_MCP_ALLOW_WRITES= --env BLE_MCP_WRITE_ALLOWLIST= --env BLE_MCP_PLUGINS= --env BLE_MCP_TOOL_SEPARATOR= --env BLE_MCP_MAX_SESSIONS= --transport stdio ble-mcp-server -- uvx ble-mcp-server ``` Replace <…> with your own values. 1 more environment variable is in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from ble-mcp-server ### Codex **Platform CLI** ```bash codex mcp add ble-mcp-server --env BLE_MCP_ALLOW_WRITES= --env BLE_MCP_WRITE_ALLOWLIST= --env BLE_MCP_PLUGINS= --env BLE_MCP_TOOL_SEPARATOR= --env BLE_MCP_MAX_SESSIONS= -- uvx ble-mcp-server ``` Replace <…> with your own values. 1 more environment variable is in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from ble-mcp-server ### Cursor **Config file** File `.cursor/mcp.json`: ```json { "mcpServers": { "ble-mcp-server": { "command": "uvx", "args": [ "ble-mcp-server" ], "env": { "BLE_MCP_ALLOW_WRITES": "", "BLE_MCP_WRITE_ALLOWLIST": "", "BLE_MCP_PLUGINS": "", "BLE_MCP_TOOL_SEPARATOR": "", "BLE_MCP_MAX_SESSIONS": "" } } } } ``` Replace <…> with your own values. 1 more environment variable is in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from ble-mcp-server ### GitHub Copilot **Config file** File `.vscode/mcp.json`: ```json { "servers": { "ble-mcp-server": { "type": "stdio", "command": "uvx", "args": [ "ble-mcp-server" ], "env": { "BLE_MCP_ALLOW_WRITES": "", "BLE_MCP_WRITE_ALLOWLIST": "", "BLE_MCP_PLUGINS": "", "BLE_MCP_TOOL_SEPARATOR": "", "BLE_MCP_MAX_SESSIONS": "" } } } } ``` Replace <…> with your own values. 1 more environment variable is in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from ble-mcp-server ### Gemini CLI **Platform CLI** ```bash gemini mcp add -e BLE_MCP_ALLOW_WRITES= -e BLE_MCP_WRITE_ALLOWLIST= -e BLE_MCP_PLUGINS= -e BLE_MCP_TOOL_SEPARATOR= -e BLE_MCP_MAX_SESSIONS= ble-mcp-server uvx ble-mcp-server ``` Replace <…> with your own values. 1 more environment variable is in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from ble-mcp-server ## When to use it - scan for a board and match it by name or service UUID - read a sensor characteristic and find out why it returns zeros - subscribe to notifications and collect a batch of readings - run a test sequence of commands against a new prototype - write down a device protocol as a spec and reuse it later ## Example prompts - Read the temperature from my SensorTag and tell me the current value - Subscribe to this characteristic and drain the first hundred notifications ## Similar - [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989 - [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918 - [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115 - [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160 - [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392 - [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872 --- NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md