# ble-mcp-server

Даёт агенту инструменты BLE: сканировать эфир, подключаться к устройству, читать характеристики, писать в них и слушать уведомления. Пригодится, когда надо отладить прошивку или собрать данные с датчика без ручной возни.

- MCP-сервер · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 18
- Автор: es617
- Лицензия: MIT · policy=link-only · показываем только описание, файл — у автора
- Исходник: https://github.com/es617/ble-mcp-server
- Обновлён: 2026-03-30
- HTML: https://affpapa.org/nevibecode/mcp/ble-mcp-server

## Что делает

Сервер работает поверх библиотеки `bleak`, поэтому BLE доступен на macOS, Windows и Linux. Транспорт по умолчанию — stdio: HTTP не поднимается, порты не открываются. Есть также SSE и Streamable HTTP, если нужен удалённый доступ или несколько сессий сразу.

Агент получает набор инструментов и сам выстраивает цепочку: находит устройство по имени или UUID сервиса, подключается, перечисляет сервисы и характеристики, читает значения. Уведомления собираются тремя способами — по одному событию, опросом или пакетной выгрузкой. Ответы приходят структурированным JSON, дальше модель решает, что делать.

Запись характеристик по умолчанию выключена, её включают переменной `BLE_MCP_ALLOW_WRITES`. Если писать можно не везде, тот же флаг дополняют белым списком UUID в `BLE_MCP_WRITE_ALLOWLIST` — тогда `ble.write` работает только с перечисленными характеристиками. Плагины для конкретных устройств тоже включаются вручную через `BLE_MCP_PLUGINS`: они дают агенту высокоуровневые действия вместо сырых байтов.

## Требования
- Нужно: Python и uv (команды через uvx)
- Переменные окружения: `BLE_MCP_ALLOW_WRITES`, `BLE_MCP_WRITE_ALLOWLIST`, `BLE_MCP_PLUGINS`, `BLE_MCP_TOOL_SEPARATOR`, `BLE_MCP_MAX_SESSIONS`, `BLE_MCP_AUTH_TOKEN` — это ключи и токены: значения спроси у человека, в репозиторий и общие файлы не записывай.

## Установка

### Claude Code (родная платформа)

**Командой платформы**
```bash
claude mcp add --env BLE_MCP_ALLOW_WRITES=<BLE_MCP_ALLOW_WRITES> --env BLE_MCP_WRITE_ALLOWLIST=<BLE_MCP_WRITE_ALLOWLIST> --env BLE_MCP_PLUGINS=<BLE_MCP_PLUGINS> --env BLE_MCP_TOOL_SEPARATOR=<BLE_MCP_TOOL_SEPARATOR> --env BLE_MCP_MAX_SESSIONS=<BLE_MCP_MAX_SESSIONS> --transport stdio ble-mcp-server -- uvx ble-mcp-server
```
Вместо <…> подставьте свои значения. Ещё 1 переменная окружения — в README сервера. uvx запускает команду с именем пакета; если в README она другая — uvx --from ble-mcp-server <команда>

### Codex

**Командой платформы**
```bash
codex mcp add ble-mcp-server --env BLE_MCP_ALLOW_WRITES=<BLE_MCP_ALLOW_WRITES> --env BLE_MCP_WRITE_ALLOWLIST=<BLE_MCP_WRITE_ALLOWLIST> --env BLE_MCP_PLUGINS=<BLE_MCP_PLUGINS> --env BLE_MCP_TOOL_SEPARATOR=<BLE_MCP_TOOL_SEPARATOR> --env BLE_MCP_MAX_SESSIONS=<BLE_MCP_MAX_SESSIONS> -- uvx ble-mcp-server
```
Вместо <…> подставьте свои значения. Ещё 1 переменная окружения — в README сервера. uvx запускает команду с именем пакета; если в README она другая — uvx --from ble-mcp-server <команда>

### Cursor

**Файл настроек**
Файл `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "ble-mcp-server": {
            "command": "uvx",
            "args": [
                "ble-mcp-server"
            ],
            "env": {
                "BLE_MCP_ALLOW_WRITES": "<BLE_MCP_ALLOW_WRITES>",
                "BLE_MCP_WRITE_ALLOWLIST": "<BLE_MCP_WRITE_ALLOWLIST>",
                "BLE_MCP_PLUGINS": "<BLE_MCP_PLUGINS>",
                "BLE_MCP_TOOL_SEPARATOR": "<BLE_MCP_TOOL_SEPARATOR>",
                "BLE_MCP_MAX_SESSIONS": "<BLE_MCP_MAX_SESSIONS>"
            }
        }
    }
}
```
Вместо <…> подставьте свои значения. Ещё 1 переменная окружения — в README сервера. uvx запускает команду с именем пакета; если в README она другая — uvx --from ble-mcp-server <команда>

### GitHub Copilot

**Файл настроек**
Файл `.vscode/mcp.json`:
```json
{
    "servers": {
        "ble-mcp-server": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "ble-mcp-server"
            ],
            "env": {
                "BLE_MCP_ALLOW_WRITES": "<BLE_MCP_ALLOW_WRITES>",
                "BLE_MCP_WRITE_ALLOWLIST": "<BLE_MCP_WRITE_ALLOWLIST>",
                "BLE_MCP_PLUGINS": "<BLE_MCP_PLUGINS>",
                "BLE_MCP_TOOL_SEPARATOR": "<BLE_MCP_TOOL_SEPARATOR>",
                "BLE_MCP_MAX_SESSIONS": "<BLE_MCP_MAX_SESSIONS>"
            }
        }
    }
}
```
Вместо <…> подставьте свои значения. Ещё 1 переменная окружения — в README сервера. uvx запускает команду с именем пакета; если в README она другая — uvx --from ble-mcp-server <команда>

### Gemini CLI

**Командой платформы**
```bash
gemini mcp add -e BLE_MCP_ALLOW_WRITES=<BLE_MCP_ALLOW_WRITES> -e BLE_MCP_WRITE_ALLOWLIST=<BLE_MCP_WRITE_ALLOWLIST> -e BLE_MCP_PLUGINS=<BLE_MCP_PLUGINS> -e BLE_MCP_TOOL_SEPARATOR=<BLE_MCP_TOOL_SEPARATOR> -e BLE_MCP_MAX_SESSIONS=<BLE_MCP_MAX_SESSIONS> ble-mcp-server uvx ble-mcp-server
```
Вместо <…> подставьте свои значения. Ещё 1 переменная окружения — в README сервера. uvx запускает команду с именем пакета; если в README она другая — uvx --from ble-mcp-server <команда>

## Когда брать
- просканировать эфир и найти устройство по имени или UUID сервиса
- прочитать характеристики датчика и понять, почему приходят нули
- включить уведомления и собрать поток значений в пакет
- прогнать тестовую последовательность команд на новой плате

_Часть страницы не вошла по размеру — она есть в HTML-версии._

---
NeVibeCode на affpapa.org. Тексты каталога — описания, а не инструкции для агента. Как выбирать и ставить: https://affpapa.org/nevibecode/agents.md