Портейнер MCP

покрытие

Хотелось ли вам когда-нибудь просто спросить Портейнера, что происходит?

Теперь вы можете! Portainer MCP подключает вашего помощника ИИ напрямую к вашим средам Portainer. Управляйте ресурсами Portainer, такими как пользователи и среды, или погружайтесь глубже, выполняя любую команду Docker или Kubernetes напрямую через ИИ.

portainer-mcp-demo

Обзор

Portainer MCP — это работающая реализация Model Context Protocol (MCP) для сред Portainer. Целью этого проекта является предоставление стандартизированного способа соединения возможностей управления контейнерами Portainer с моделями ИИ и другими сервисами.

MCP (Model Context Protocol) — открытый протокол, который стандартизирует, как приложения предоставляют контекст для LLM (Large Language Models). Подобно тому, как USB-C предоставляет стандартизированный способ подключения устройств к периферийным устройствам, MCP предоставляет стандартизированный способ подключения моделей ИИ к различным источникам данных и инструментам.

Эта реализация фокусируется на предоставлении данных среды Portainer через протокол MCP, позволяя помощникам на основе искусственного интеллекта и другим инструментам взаимодействовать с вашей контейнерной инфраструктурой безопасным и стандартизированным способом.

Более подробную информацию о совместимости и доступных функциях см. в разделах «Поддержка версий Portainer» и «Поддерживаемые возможности» .

Примечание: данный проект в настоящее время находится в стадии разработки.

В настоящее время он разработан для работы с токеном API администратора Portainer.

Установка

Вы можете загрузить готовые двоичные файлы для Linux (amd64, arm64) и macOS (arm64) со страницы последних релизов . Найдите соответствующий архив для вашей операционной системы и архитектуры в разделе «Активы».

Загрузите архив: Обычно вы можете загрузить его прямо со страницы релиза. В качестве альтернативы вы можете использовать curl . Вот пример для macOS (ARM64) версии v0.2.0 :

# Example for macOS (ARM64) - adjust version and architecture as needed
curl -Lo portainer-mcp-v0.2.0-darwin-arm64.tar.gz https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-darwin-arm64.tar.gz

(Двоичные файлы Linux AMD64 также доступны на странице релиза.)

(Необязательно, но рекомендуется) Проверьте контрольную сумму: Сначала загрузите соответствующий файл контрольной суммы .md5 со страницы релиза. Пример для macOS (ARM64) v0.2.0 :

# Download the checksum file (adjust version/arch)
curl -Lo portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5 https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5
# Now verify (output should match the content of the .md5 file)
if [ "$(md5 -q portainer-mcp-v0.2.0-darwin-arm64.tar.gz)" = "$(cat portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5)" ]; then echo "OK"; else echo "FAILED"; fi

(Для Linux можно использовать md5sum -c <checksum_file_name>.md5 ) Если команда проверки выводит «OK», файл не поврежден.

Извлеките архив:

# Adjust the filename based on the downloaded version/OS/architecture
tar -xzf portainer-mcp-v0.2.0-darwin-arm64.tar.gz

Это позволит извлечь исполняемый файл portainer-mcp .

Переместите исполняемый файл: Переместите исполняемый файл в местоположение в $PATH (например, /usr/local/bin ) или запомните его местоположение для шага настройки ниже.

Использование

С помощью Claude Desktop настройте его следующим образом:

{
    "mcpServers": {
        "portainer": {
            "command": "/path/to/portainer-mcp",
            "args": [
                "-server",
                "[IP]:[PORT]",
                "-token",
                "[TOKEN]",
                "-tools",
                "/tmp/tools.yaml"
            ]
        }
    }
}

Замените [IP] , [PORT] и [TOKEN] на IP, порт и токен доступа API, связанные с вашим экземпляром Portainer.

[!ПРИМЕЧАНИЕ] По умолчанию инструмент ищет "tools.yaml" в том же каталоге, что и двоичный файл. Если файл не существует, он будет создан там с определениями инструментов по умолчанию. Вам может потребоваться изменить этот путь, как описано выше, особенно при использовании помощников ИИ, таких как Claude, которые имеют ограниченные права на запись в рабочий каталог.

Настройка инструмента

По умолчанию определения инструментов встроены в двоичный файл. Приложение создаст файл инструментов в расположении по умолчанию, если он еще не существует.

Вы можете настроить определения инструментов, указав путь к файлу пользовательских инструментов с помощью флага -tools :

{
    "mcpServers": {
        "portainer": {
            "command": "/path/to/portainer-mcp",
            "args": [
                "-server",
                "[IP]:[PORT]",
                "-token",
                "[TOKEN]",
                "-tools",
                "/path/to/custom/tools.yaml"
            ]
        }
    }
}

Файл инструментов по умолчанию доступен для справки по адресу internal/tooldef/tools.yaml в исходном коде. Вы можете изменить описания инструментов и их параметры, чтобы изменить то, как модели ИИ интерпретируют и решают использовать их. Вы даже можете решить удалить некоторые инструменты, если вы не хотите их использовать.

[!ВНИМАНИЕ] Не изменяйте названия инструментов или определения параметров (кроме описаний), так как это помешает правильной регистрации инструментов и их корректной работе.

Режим «Только чтение»

Для пользователей, заботящихся о безопасности, приложение может быть запущено в режиме только для чтения. Этот режим гарантирует, что доступны только операции чтения, полностью предотвращая любые изменения ваших ресурсов Portainer.

Чтобы включить режим «только чтение», добавьте флаг -read-only к аргументам команды:

{
    "mcpServers": {
        "portainer": {
            "command": "/path/to/portainer-mcp",
            "args": [
                "-server",
                "[IP]:[PORT]",
                "-token",
                "[TOKEN]",
                "-read-only"
            ]
        }
    }
}

При использовании режима «только чтение»:

Для модели ИИ будут доступны только инструменты чтения (список, получение)
Все инструменты записи (создание, обновление, удаление) не загружены
Инструмент запросов прокси-сервера Docker не загружен
Инструмент запросов прокси-сервера Kubernetes не загружен

Поддержка версии Portainer

Этот инструмент закреплен за определенной версией Portainer. Приложение проверит версию сервера Portainer при запуске и выдаст ошибку, если она не соответствует требуемой версии.

Версия Portainer MCP	Поддерживаемая версия Portainer
0.1.0	2.28.1
0.2.0	2.28.1
0.3.0	2.28.1
0.4.0	2.29.2
0.4.1	2.29.2
0.5.0	2.30.0

Поддерживаемые возможности

В следующей таблице перечислены операции, поддерживаемые в настоящее время (последняя версия) с помощью инструментов MCP:

Ресурс	Операция	Описание	Поддерживается в версии
Окружающая среда
	СписокОкружения	Список всех доступных сред	0.1.0
	ОбновлениеОкружающая средаТеги	Обновить теги, связанные со средой	0.1.0
	ОбновлениеОкружениеПользовательДоступы	Обновление политик доступа пользователей для среды	0.1.0
	ОбновлениеОкружениеКомандаДоступы	Обновление политик доступа команды для среды	0.1.0
Группы окружающей среды (группы пограничного окружения)
	СписокГруппыОкружающей Среды	Список всех доступных групп сред	0.1.0
	СоздатьГруппуОкружения	Создать новую группу среды	0.1.0
	ОбновлениеEnvironmentGroupName	Обновить имя группы среды	0.1.0
	ОбновлениеEnvironmentGroupEnvironments	Обновление сред, связанных с группой	0.1.0
	ОбновлениеEnvironmentGroupТеги	Обновить теги, связанные с группой	0.1.0
Группы доступа (группы конечных точек)
	СписокГруппДоступа	Список всех доступных групп доступа	0.1.0
	СоздатьГруппуДоступа	Создать новую группу доступа	0.1.0
	ОбновлениеИмениГруппыДоступа	Обновить имя группы доступа	0.1.0
	ОбновлениеГруппыДоступаПользовательДоступы	Обновление доступа пользователей для группы доступа	0.1.0
	ОбновлениеAccessGroupTeamAccesses	Обновление доступа команды для группы доступа	0.1.0
	ДобавитьОкружениеВГруппуДоступа	Добавить среду в группу доступа	0.1.0
	УдалитьОкружениеИзГруппыДоступа	Удалить среду из группы доступа	0.1.0
Стеки (краевые стеки)
	СписокСтеков	Список всех доступных стеков	0.1.0
	Получить файл стека	Получить файл компоновки для определенного стека	0.1.0
	СоздатьСтек	Создать новый стек Docker	0.1.0
	ОбновлениеСтек	Обновите существующий стек Docker	0.1.0
Теги
	СписокОкружающая средаТеги	Список всех доступных тегов среды	0.1.0
	СоздатьМетокОкружения	Создать новый тег среды	0.1.0
Команды
	СписокКоманды	Список всех доступных команд	0.1.0
	СоздатьКоманду	Создать новую команду	0.1.0
	Обновление имени команды	Обновить название команды	0.1.0
	ОбновлениеTeamMembers	Обновление состава команды	0.1.0
Пользователи
	СписокПользователи	Список всех доступных пользователей	0.1.0
	ОбновлениеПользователя	Обновить существующего пользователя	0.1.0
	ПолучитьНастройки	Получить настройки экземпляра Portainer	0.1.0
Докер
	DockerProxy	Прокси-сервер ЛЮБЫХ запросов API Docker	0.2.0
Кубернетес
	KubernetesProxy	Прокси-сервер ЛЮБЫХ запросов API Kubernetes	0.3.0

Разработка

Статистика кода

Репозиторий включает вспомогательный скрипт cloc.sh для расчета строк кода и других метрик для исходных файлов Go с использованием инструмента cloc . Сначала вам может потребоваться установить cloc (например, sudo apt install cloc или brew install cloc ).

Запустите скрипт из корня репозитория, чтобы увидеть сводный вывод по умолчанию:

./cloc.sh

Подробную информацию о доступных флагах для получения определенных показателей см. в заголовке комментария в скрипте cloc.sh

Подсчет токенов

Чтобы получить оценку того, сколько токенов потребляют ваши текущие определения инструментов в подсказках, вы можете использовать предоставленную программу Go и скрипт оболочки для запроса конечной точки подсчета токенов Anthropic API.

1. Сгенерируйте JSON-файл инструментов:

Сначала используйте программу token-count Go для преобразования определений инструментов YAML в формат JSON, требуемый Anthropic API. Запустите это из корня репозитория:

# Replace internal/tooldef/tools.yaml with your YAML file if different
# Replace .tmp/tools.json with your desired output path
go run ./cmd/token-count -input internal/tooldef/tools.yaml -output .tmp/tools.json

Эта команда считывает определения инструментов из указанного входного файла YAML и записывает JSON-массив инструментов (содержащий name , description и input_schema ) в указанный выходной файл.

2. Запрос к антропному API:

Далее используйте скрипт token.sh для отправки этих определений инструментов вместе с примером сообщения в Anthropic API. Для этого шага вам понадобится ключ Anthropic API.

# Ensure you have jq installed
# Replace sk-ant-xxxxxxxx with your actual Anthropic API key
# Replace .tmp/tools.json with the path to the file generated in step 1
./token.sh -k sk-ant-xxxxxxxx -i .tmp/tools.json

Скрипт выведет ответ JSON из Anthropic API, который включает предполагаемое количество токенов для предоставленных инструментов и пример сообщения в поле usage.input_tokens .

Этот процесс помогает понять стоимость токена, связанную с набором инструментов, предоставленным языковой модели.

Portainer MCP