API v1

MosaicVPN API

Управляйте VPN как программист: локальный REST API на каждом устройстве, MCP-сервер для ИИ-ассистентов и облачный API аккаунта. Одинаковая поверхность на Windows, Linux и Android.

Локальный REST API

Клиент MosaicVPN поднимает HTTP-сервер только на 127.0.0.1:19080 (или 19081, если порт занят). Из сети он недоступен — это ваш личный пульт управления на вашем же устройстве.

Полная машина-читаемая спецификация: GET http://127.0.0.1:19080/openapi.json (OpenAPI 3.1, можно скормить Swagger UI, Postman, codegen'у).

Метод и путь	Что делает
`GET /status`	Статус туннеля: connected, сервер, группа, ошибки
`GET /servers`	Список серверов и групп с задержкой
`GET /health`	Прозвон всех серверов с результатами
`POST /connect/{id}`	Подключиться к серверу/группе по id
`POST /disconnect`	Разорвать туннель
`POST /find-stable`	Автовыбор самого стабильного сервера
`GET /v1/prefs`	Настройки: режим, split-туннелирование по приложениям
`PUT /v1/prefs`	Частичное обновление настроек (списки заменяются целиком)
`GET /v1/presets`	Встроенные пресеты маршрутизации
`GET /openapi.json`	OpenAPI-спецификация этого API

Пример: статус

curl http://127.0.0.1:19080/status
# {"connected":true,"state":"connected","server":{"id":"nl-1","name":"Амстердам"},
#    "active_group_id":"auto-nl","tunnel_mode":"tun"}

Пример: исключить банковские приложения из VPN

curl -X PUT http://127.0.0.1:19080/v1/prefs \
  -H "Content-Type: application/json" \
  -d '{"bypass_packages":["ru.sberbankmobile","com.idamob.tinkoff.android"]}'

# {"updated":1,"prefs":{"routing_mode":"rule",
#    "bypass_packages":["ru.sberbankmobile","com.idamob.tinkoff.android"],
#    "proxy_packages":[],"adblock":false,"kill_switch":true}}

bypass_packages — приложения, которые ходят напрямую (банки, такси); proxy_packages — режим «только эти приложения через VPN». Список пакетов смотрите в приложении: Ещё → Приложения.

MCP-сервер для ИИ-ассистентов

В репозитории лежит mcp/mosaic_mcp.py — MCP-сервер поверх локального REST API (Python 3.10+, без зависимостей). Восемь инструментов: vpn_status, vpn_servers, vpn_connect, vpn_disconnect, vpn_find_stable, vpn_get_prefs, vpn_set_prefs, account_profile.

Claude Desktop (Windows)

%APPDATA%\Claude\claude_desktop_config.json:
{
  "mcpServers": {
    "mosaicvpn": {
      "command": "python",
      "args": ["C:\\Путь\\К\\mosaic_mcp.py"]
    }
  }
}

Cursor / VS Code (любая ОС)

.cursor/mcp.json / .vscode/mcp.json:
{
  "mcpServers": {
    "mosaicvpn": {
      "command": "python3",
      "args": ["/path/to/mosaic_mcp.py"],
      "env": {
        "MOSAIC_LOCAL_API": "http://127.0.0.1:19080",
        "MOSAIC_API_TOKEN": "ваш-токен-необязателен"
      }
    }
  }
}

Пример диалога

«Подключись к Амстердаму и исключи Сбербанк из VPN» — ассистент вызовет vpn_servers, затем vpn_connect и vpn_set_prefs с bypass_packages.

Облачный API аккаунта

Аккаунтные данные (дни, баланс, трафик, платежи) доступны на https://sub.zxc1x1.ru с токеном, который выдаёт бот или приложение.

Путь	Что возвращает
`GET /api/billing/profile?token=…`	Профиль: дни, баланс, трафик, устройства
`GET /api/billing/payments?token=…`	История платежей
`POST /api/auth/login`	Логин (email + пароль) → сессия
`POST /api/checkout/create`	Создать счёт на оплату

Локальный API слушает только 127.0.0.1 — не пробрасывайте порт наружу. Токен облака — как пароль: храните в менеджере секретов, не коммитьте.

Спецификации: modelcontextprotocol.io · OpenAPI 3.1 · MosaicVPN v0.3.73