ioBroker.mcp

Сервер MCP для ioBroker

Описание

Этот адаптер предоставляет доступ к ioBroker в качестве сервера MCP (Model Context Protocol) , поэтому клиенты, поддерживающие MCP (например, Claude Desktop), могут считывать данные и управлять вашей установкой с помощью четко определенного набора инструментов.

Функции

• Сервер MCP использует протокол Streamable HTTP (/mcp конечная точка)
• Настраиваемый веб-сервер HTTP/HTTPS
• Настраиваемый порт и адрес привязки
• Дополнительная аутентификация
• Дополнительная поддержка SSL/TLS
• Диагностика сети (ICMP ping / TCP probe) для устранения неполадок в работе сетевых адаптеров.
• Поиск в репозитории адаптеров для рекомендации устанавливаемых адаптеров.

Режимы работы

Адаптер может работать в двух режимах:

1. Автономный режим (по умолчанию) — запускает собственный веб-сервер на настроенном порту. Конечная точка MCP — [укажите адрес].http(s)://<host>:<port>/mcp .

2. Веб-расширение — оно работает внутри существующегоweb Экземпляр адаптера используется совместно с веб-сервером (порт, аутентификация, SSL). Выберите целевой веб-экземпляр в конфигурации администратора («Расширить веб-адаптер»). Затем конечная точка MCP будет обслуживаться через веб-адаптер, например.http(s)://<host>:8082/mcp/ .

   При выборе веб-экземпляра настройки автономного сервера (порт, адрес привязки, аутентификация, SSL) скрываются, поскольку они наследуются от выбранного экземпляра.web пример.

Конфигурация

Адаптер можно настроить через административный интерфейс ioBroker с помощью JSONConfig:

Конфигурация сервера

• Расширить веб-адаптер : выберитеweb Экземпляр для запуска в качестве расширения. Оставьте поле пустым для автономного запуска.
• Порт : Порт, на котором веб-сервер будет прослушивать запросы (по умолчанию: 8093) – только для автономного режима.
• Адрес привязки : IP-адрес, к которому будет привязан сервер (0.0.0.0 для всех интерфейсов) – только для автономного режима.

Аутентификация

• Включить аутентификацию : Включить аутентификацию пользователей ioBroker для веб-сервера.
• Пользователь по умолчанию : Пользователь ioBroker, с правами которого выполняется каждый запрос MCP (по умолчанию:admin Все операции чтения и записи объектов/состояния, выполняемые инструментами, осуществляются от имени этого пользователя, поэтому применяются списки контроля доступа (ACL) этого пользователя. Простое имя, например,operator автоматически расширяется доsystem.user.operator При запуске в качестве веб-расширения, если пользователь здесь не указан, хостweb Используется пользователь по умолчанию для данного экземпляра.

OAuth

Клиенты MCP, такие как Claude Desktop, подключаются через браузер, а не с помощью токена, созданного вручную. Клиент самостоятельно обнаруживает сервер, пользователь входит в систему и подтверждает авторизацию, и клиент никогда не видит пароль от ioBroker.

• Включить OAuth (вход через браузер) : В автономном режиме это требует включения аутентификации . В качестве веб-расширения выбранный вариантweb Экземпляр предоставляет доступ для авторизации, поэтому OAuth также должен быть включен там («Разрешить сторонним клиентам») — в противном случае клиенты MCP будут получать только перенаправление на страницу входа, которую они не смогут использовать.
• Публичный URL : внешний адрес этого сервера без указания пути, например.https://iobroker.example.com Требуется при использовании обратного прокси-сервера: URL-адреса, публикуемые для обнаружения OAuth, должны быть теми, к которым клиент фактически имеет доступ. Как веб-расширение, оно должно соответствовать общедоступному URL-адресу, настроенному вweb пример.
• Разрешить самостоятельную регистрацию клиентов : позволить клиентам MCP регистрироваться самостоятельно (по умолчанию: включено ). При отключении этой опции каждому клиенту сначала придется регистрироваться вручную. В режиме веб-расширения это и естьweb Это настройка экземпляра, поэтому данная опция здесь скрыта.

HTTPS необходим для всего, кромеlocalhost — поток данных проходит через браузер пользователя, и клиенты MCP отказываются от обычного доступа.http:// для удалённых хостов.

Токены доступа привязаны к этой конечной точке, поэтому токен, выданный для другой службы на том же сервере, будет отклонен. Клиенты могут повторно удалить свои токены черезPOST /oauth/revoke .

Разрешения

• Разрешить установку состояний : Разрешить клиентам MCP записывать значения состояний (set_state иset_states инструменты). По умолчанию: включено .
• Пометить состояние установки как деструктивное : Объявитьset_state иset_states сdestructiveHint: true Таким образом, клиенты MCP могут выдавать предупреждения перед записью состояния. По умолчанию: включено . Если выключено, оба инструмента объявляются как выполняющие неразрушающую запись.readOnlyHint пребываниеfalse ); Вопрос о том, будет ли клиент по-прежнему запрашивать подтверждение, зависит от самого клиента.
• Разрешить изменение объектов/файлов : Разрешить клиентам MCP создавать/изменять/удалять объекты и файлы (set_object ,delete_object ,create_state ,create_scene ,write_file ,delete_file ,rename_file иmkdir инструменты). По умолчанию: выключено . Если выключено, эти инструменты вообще не отображаются.

Настройка SSL/TLS

• Включить HTTPS : Включите HTTPS/SSL для безопасных соединений.
• Открытый сертификат : путь к файлу открытого сертификата.
• Закрытый ключ : путь к файлу закрытого ключа.
• Цепочка сертификатов : путь к файлу цепочки сертификатов (необязательно)

Соединение ChatGPT и Клода

В каталогах коннекторов Claude и ChatGPT пока нет официального приложения ioBroker. До тех пор добавляйте ioBroker как пользовательский коннектор . Доступ к вашей установке можно получить двумя способами:

A: через ioBroker Remote

1. Настройте этот адаптер (автономный или как веб-расширение). Оставьте параметры «Включить аутентификацию» и «Включить OAuth» выключенными : вход в систему происходит на iobroker.pro, а ioBroker.iot подключается к этому экземпляру локально без учетных данных. В качестве веб-расширения выбранный адаптер будет работать корректно.web Экземпляр также не должен использовать аутентификацию. Порт не обязательно должен быть доступен из интернета.
2. В настройках ioBroker.iot (войдя в систему с помощью своей учетной записи ioBroker.pro) включите параметр «Разрешить удаленный доступ» и выберите этот экземпляр в качестве экземпляра MCP . Сохраните изменения.
3. Добавьте коннектор в Claude или ChatGPT (см. ниже) с URL-адресом.https://mcp.iobroker.in/mcp .
4. Откроется страница входа «Подключиться к ioBroker»: введите адрес электронной почты и пароль вашей учетной записи ioBroker.pro и нажмите «Войти и разрешить» . Разрешайте подключение только в том случае, если вы только что настроили его самостоятельно.

Доступ предоставляется при наличии подтвержденного адреса электронной почты и действующей лицензии ioBroker.pro. Новые учетные записи могут использовать сервис в течение 7 дней после регистрации без лицензии.

Полезно знать:

• ioBroker.iot должен быть подключен к облаку, иначе клиент получит ошибку "ioBroker находится в автономном режиме".
• Обновления в режиме реального времени (подписка на ресурсы) недоступны через удаленный доступ. Все инструменты работают.
• После перезапуска экземпляра MCP клиент самостоятельно запускает новую сессию.
• Удаление коннектора в клиенте прекращает доступ. Уже выданный токен доступа остается действительным до одного часа. Чтобы немедленно остановить доступ, очистите экземпляр MCP в файле ioBroker.iot.

B: напрямую на ваш сервер

1. Включите аутентификацию и OAuth . Если вы используете веб-расширение, включите OAuth («Разрешить сторонним клиентам») в настройках.web также и в одном из таких случаев.
2. Обеспечьте доступность сервера через HTTPS из интернета и введите этот адрес в качестве публичного URL .
3. Используйте URL-адресhttps://<your public address>/mcp (в виде веб-расширения)https://<your public address>/mcp/ ) в клиенте и войдите в систему под учетной записью пользователя ioBroker.

Клод (claude.ai, Claude Desktop)

На всех тарифных планах доступны пользовательские коннекторы, бесплатный план ограничен одним пользовательским коннектором.

1. Откройте «Настройка» → «Коннекторы» , нажмите «+» и выберите «Добавить пользовательский коннектор» .
2. Введите имя (например)ioBroker ) и URL-адрес сервера. Расширенные настройки (идентификатор и секрет клиента OAuth) остаются пустыми, Клод регистрируется.
3. Нажмите «Добавить» . Если вход в систему не запускается автоматически, нажмите «Подключить» рядом с коннектором.
4. В чате нажмите + (в левом нижнем углу) → Коннекторы и включите ioBroker .

Для команд и предприятий: сначала владелец добавляет коннектор в разделе «Настройки организации» → «Коннекторы» → «Добавить» → «Пользовательский» → «Веб» . Затем участники открывают раздел «Настройка» → «Коннекторы» и нажимают «Подключить» .

Кодекс Клода:

claude mcp add --transport http iobroker https://mcp.iobroker.in/mcp

Затем запустите/mcp В коде Клода выберитеiobroker и войдите в систему через браузер.

ChatGPT

Для пользовательских подключений MCP требуется режим разработчика , который доступен для учетных записей Plus, Pro, Business, Enterprise и Education в веб-версии ChatGPT. В рабочих пространствах Business и Enterprise администратор должен сначала разрешить его использование.

1. Откройте «Настройки» → «Безопасность», войдите в систему и включите режим разработчика .
2. Откройте плагины ChatGPT и нажмите + .
3. Введите имя (например)ioBroker ) и описание (например, "Считывает данные и управляет моим умным домом ioBroker"). В разделе "Подключение" выберите "Публичная конечная точка" и введите URL-адрес сервера. В качестве метода аутентификации выберите OAuth .
4. Создайте соединение и войдите в систему. Затем ChatGPT отобразит список инструментов ioBroker.
5. В чате откройте + → Режим разработчика и выберите ioBroker . Полезно явно указать имя ioBroker в запросе, например: "Используйте ioBroker для выключения света на кухне".

ChatGPT помечает подключения в режиме разработчика как сопряженные с повышенным риском и запрашивает подтверждение перед выполнением операций записи.

Названия пунктов меню взяты со страниц справки Claude и ChatGPT (сентябрь 2026 г.) и могут измениться.

Рекомендации

• Назначьте пользователя по умолчанию , предоставив ему только те права, которые должны быть у ИИ. Каждый инструмент будет работать со своими правами доступа.
• Отключите параметр «Разрешить изменение объектов/файлов», если он вам не нужен.
• Оставьте параметр "Состояния Марка" в режиме "деструктивные" включенным, чтобы клиенты спрашивали разрешения, прежде чем что-либо менять.

Конечная точка MCP

Сервер MCP обслуживается по адресу:POST/GET/DELETE /mcp с использованием транспортного протокола HTTP Streamable с сохранением состояния для каждой сессии (отслеживаемого черезMcp-Session-Id (заголовок). Направьте свой MCP-клиент по следующему адресу:

• автономный:http(s)://<host>:<port>/mcp
• веб-расширение:http(s)://<host>:<webPort>/mcp/

Доступные инструменты

Доступ ко всем объектам/состоянию осуществляется с правами, предоставленными настроенным пользователем по умолчанию . Инструменты записи регистрируются только в том случае, если включена соответствующая опция прав доступа.

Ресурсы и оперативные обновления (SSE)

Состояния и объекты также доступны в качестве ресурсов MCP с использованием канонической схемы URI ioBroker, поэтому клиенты могут читать их и подписываться на них. Сервер передает изменения через поток Streamable HTTP SSE.notifications/resources/updated ).

• Штаты:iobstate://<id> (напримерiobstate://javascript.0.temperature ) –resources/read возвраты{ id, val, ack, ts, lc, q } .
• Объекты:iobobject://<id> (напримерiobobject://system.adapter.admin.0 ) –resources/read возвращает объект.
• Журналы:ioblog://all (каждый источник) илиioblog://<source> (напримерioblog://admin.0 ) –resources/read возвращает последние строки лога ({ source, logs: [{ ts, level, source, message }] } Подписка включает пересылку журналов для адаптера; каждая новая соответствующая строка запускаетnotifications/resources/updated .
• resources/subscribe Подписывается на состояние/объект/журнал базового ioBroker; при каждом изменении клиент получает уведомление.notifications/resources/updated для этого URI и перечитывает его.resources/unsubscribe останавливает это.

Подписки отслеживаются для каждой сессии и подсчитываются по количеству ссылок, поэтому адаптер подписывается на состояние/объект только один раз, независимо от того, сколько клиентов/сессий следят за ним, и отписывается, когда последний клиент покидает систему.

(Использование файлов)iobfile://<adapter>/<path> по той же схеме; они доступны черезread_file /write_file (В качестве инструментов, а не в качестве ресурсов, на которые можно подписаться.)

Показатели состояния здоровья (не относящиеся к MCP)

• GET / - Основная информация о сервере
• GET /status - Состояние сервера, время безотказной работы и количество активных сессий.
• GET /api/info- Информация об адаптере

Changelog

WORK IN PROGRESS

• (@GermanBluefox) Added instructions for connecting ChatGPT and Claude (via ioBroker Remote or directly)

1.1.6 (2026-09-15)

• (@GermanBluefox) Added IP address selector
• (@GermanBluefox) New option "Mark setting states as destructive" (default on): set_state/set_states can be declared as non-destructive writes

1.1.4 (2026-09-03)

• (@GermanBluefox) read_file reads large files in chunks: new optional offset/length parameters, at most 512 KiB per call by default; the result now contains size, offset, length, truncated and nextOffset (MCP clients reject tool results above 1 MB, ioBroker/ioBroker.mcp#63)

1.1.3 (2026-09-03)

• (ioBroker-Bot) Adapter requires admin >= 7.8.23 now.
• (@GermanBluefox) Updated packages

1.1.2 (2026-08-26)

• (@GermanBluefox) Node.js 22 is required now
• (@GermanBluefox) Corrected OAuth page

1.1.0 (2026-08-04)

• (@GermanBluefox) Added OAuth: MCP clients can now be connected through a browser login instead of a manually created token
• (@GermanBluefox) OAuth also works as a web extension, using the host web instance as the authorization server (requires OAuth enabled there too)
• (@GermanBluefox) Updated @iobroker/mcp-server and @iobroker/webserver

License

MIT License

Copyright (c) 2025-2026 ioBroker

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.