StarLine MCP

MCP-сервер для управления автосигнализацией StarLine через ИИ-агента (Claude и др.).

Агент вызывает понятные инструменты (list_devices, get_status, set_engine…), а сервер прячет всю «грязь»: 4-шаговую авторизацию StarLineID, кэш токенов и маппинг команд в облачный API.

AI-агент (Claude) ──tools──► StarLine MCP ──REST──► облако StarLine ──GSM──► блок в машине

Архитектура

Слой	Файл	Ответственность
Конфиг	config.py	учётные данные из .env
Авторизация	auth.py	getCode → getToken → user/login → auth.slid, кэш slnet (24ч)
Клиент API	client.py	список/статус устройств, отправка команд, авто-переавторизация
MCP-сервер	server.py	инструменты для агента

Безопасность

Инструменты разделены на два класса:

• read-only (list_devices, get_status, get_location) — выполняются свободно.
• команды управления (set_security, set_engine, set_heater, set_channel) — отказывают без confirm=true. Агент не должен подставлять confirm сам — подтверждение исходит от человека. Рекомендуется дополнительно требовать approval на эти инструменты в настройках хоста (Claude Desktop / Claude Code permissions).

⚠️ Запуск двигателя и снятие с охраны — физические действия с реальной машиной. Относитесь к ним как к необратимым.

Установка

Изолированный venv обязателен: на машине бывает несколько Python, а голый python в конфиге MCP-хоста резолвится непредсказуемо (главная причина «не запускается»).

cd "C:/GIT/StarLine MCP"
py -3.12 -m venv .venv
.venv/Scripts/python.exe -m pip install -e .   # ставит пакет + зависимости в venv
cp .env.example .env                            # затем заполнить

После -e . пакет импортируется из venv — PYTHONPATH задавать не нужно.

Самодиагностика (проверяет импорты и конфиг, печатает в stderr):

.venv/Scripts/python.exe -m starline_mcp.server --healthcheck

.env:

STARLINE_APP_ID=...         # из https://my.starline.ru/developer
STARLINE_APP_SECRET=...
STARLINE_LOGIN=...          # аккаунт my.starline.ru
STARLINE_PASSWORD=...

Проверка доступа

.venv/Scripts/python.exe -m starline_mcp.check_auth

Залогинится и выведет список ваших устройств со статусом. Это лучший первый шаг — убедиться, что API-доступ реально работает, до подключения к агенту.

Запуск MCP-сервера

.venv/Scripts/python.exe -m starline_mcp.server

Подключение к Claude Code: в корне уже лежит .mcp.json с абсолютным путём к venv (не голый python — это принципиально):

{
  "mcpServers": {
    "starline": {
      "command": "C:/GIT/StarLine MCP/.venv/Scripts/python.exe",
      "args": ["-m", "starline_mcp.server"],
      "cwd": "C:/GIT/StarLine MCP",
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

Если хост (Hermes/Claude Code) «не видит модуль» — почти всегда это голый python в команде вместо абсолютного пути к .venv/Scripts/python.exe. Не подмешивай PYTHONPATH и не плоди wrapper-скрипты — после pip install -e . это не нужно.

Подключение к Claude Code

В корне лежит .mcp.json — Claude Code подхватит сервер автоматически при запуске в этой папке. Список инструментов появится после подтверждения подключения MCP-сервера.

Рекомендация: в настройках прав потребуй approval на инструменты set_* (команды управления), чтобы каждое физическое действие с машиной подтверждалось вручную.

Статус

• [x] Авторизация (4 шага) + кэш токенов
• [x] Чтение: список устройств, статус, GPS, баланс SIM
• [x] Команды с подтверждением: охрана, двигатель, подогреватель, доп. канал, поиск авто
• [x] Проверено на живом аккаунте
• [x] Авто-выбор команды под модель блока (ign vs ign_start/ign_stop)
• [x] Проверка поддержки команды конкретным блоком (по controls)
• [x] Кэш списка устройств (TTL 15с)
• [x] Конфиг .mcp.json для Claude Code
• [ ] Боевая проверка отправки команд (требует согласия владельца — физическое действие)
• [ ] Обработка 2FA в интерактиве (если включится на аккаунте)

Источники

Эндпоинты и алгоритмы сверены по:

• https://github.com/Anonym-tsk/starline (pip-пакет starline)
• homeassistant/components/starline
• https://developer.starline.ru/