포테이너 MCP

적용 범위

포르타이너에게 무슨 일이 일어나고 있는지 직접 물어볼 수 있다면 좋겠다고 생각한 적이 있나요?

이제 가능합니다! Portainer MCP는 AI 어시스턴트를 Portainer 환경에 직접 연결합니다. 사용자 및 환경과 같은 Portainer 리소스를 관리하거나, AI를 통해 Docker 또는 Kubernetes 명령을 직접 실행하여 더 심층적인 작업을 수행할 수 있습니다.

포테이너-MCP-데모

개요

Portainer MCP는 Portainer 환경을 위한 모델 컨텍스트 프로토콜(MCP) 의 개발 중인 구현입니다. 이 프로젝트는 Portainer의 컨테이너 관리 기능을 AI 모델 및 기타 서비스와 연결하는 표준화된 방법을 제공하는 것을 목표로 합니다.

MCP(Model Context Protocol)는 애플리케이션이 LLM(Large Language Models)에 컨텍스트를 제공하는 방식을 표준화하는 개방형 프로토콜입니다. USB-C가 주변 기기에 장치를 연결하는 표준화된 방식을 제공하는 것처럼, MCP는 AI 모델을 다양한 데이터 소스 및 도구에 연결하는 표준화된 방식을 제공합니다.

이 구현은 MCP 프로토콜을 통해 Portainer 환경 데이터를 공개하는 데 중점을 두고, AI 어시스턴트와 기타 도구가 안전하고 표준화된 방식으로 컨테이너화된 인프라와 상호 작용할 수 있도록 합니다.

호환성 및 사용 가능한 기능에 대한 자세한 내용은 Portainer 버전 지원 및 지원되는 기능 섹션을 참조하세요.

참고: 이 프로젝트는 현재 개발 중입니다.

현재는 Portainer 관리자 API 토큰과 함께 작동하도록 설계되었습니다.

설치

최신 릴리스 페이지 에서 Linux(amd64, arm64) 및 macOS(arm64)용 사전 빌드된 바이너리를 다운로드할 수 있습니다. "자산" 섹션에서 사용 중인 운영 체제 및 아키텍처에 맞는 아카이브를 찾으세요.

아카이브 다운로드: 일반적으로 릴리스 페이지에서 직접 다운로드할 수 있습니다. 또는 curl 사용할 수도 있습니다. 다음은 macOS(ARM64) 버전 v0.2.0 의 예시입니다.

지엑스피1

(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] Portainer 인스턴스와 연결된 IP, 포트 및 API 액세스 토큰으로 바꾸세요.

[!NOTE] 기본적으로 도구는 바이너리와 동일한 디렉터리에서 "tools.yaml" 파일을 찾습니다. 파일이 없으면 기본 도구 정의를 사용하여 해당 디렉터리에 생성됩니다. 특히 Claude와 같이 작업 디렉터리에 대한 쓰기 권한이 제한된 AI 어시스턴트를 사용하는 경우, 위에서 설명한 대로 이 경로를 수정해야 할 수 있습니다.

도구 사용자 정의

기본적으로 도구 정의는 바이너리에 내장됩니다. 도구 파일이 없으면 애플리케이션에서 기본 위치에 자동으로 생성합니다.

-tools 플래그를 사용하여 사용자 정의 도구 파일 경로를 지정하여 도구 정의를 사용자 정의할 수 있습니다.

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

기본 도구 파일은 소스 코드의 internal/tooldef/tools.yaml 에서 참조할 수 있습니다. 도구 및 매개변수에 대한 설명을 수정하여 AI 모델이 도구를 해석하고 사용하는 방식을 변경할 수 있습니다. 사용하지 않으려는 도구는 삭제할 수도 있습니다.

[!경고] 도구 이름이나 매개변수 정의(설명 제외)를 변경하지 마십시오. 변경하면 도구가 제대로 등록되지 않고 제대로 작동하지 않습니다.

읽기 전용 모드

보안에 민감한 사용자를 위해 애플리케이션을 읽기 전용 모드로 실행할 수 있습니다. 이 모드에서는 읽기 작업만 허용되므로 Portainer 리소스에 대한 어떠한 수정도 완전히 차단됩니다.

읽기 전용 모드를 활성화하려면 명령 인수에 -read-only 플래그를 추가하세요.

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

읽기 전용 모드를 사용하는 경우:

AI 모델에서는 읽기 도구(목록, 가져오기)만 사용할 수 있습니다.
모든 쓰기 도구(생성, 업데이트, 삭제)가 로드되지 않았습니다.
Docker 프록시 요청 도구가 로드되지 않았습니다.
Kubernetes 프록시 요청 도구가 로드되지 않았습니다.

포테이너 버전 지원

이 도구는 특정 버전의 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
환경 그룹(Edge 그룹)
	환경 그룹 목록	사용 가능한 모든 환경 그룹 나열	0.1.0
	환경 그룹 생성	새로운 환경 그룹을 만듭니다	0.1.0
	업데이트 환경 그룹 이름	환경 그룹의 이름 업데이트	0.1.0
	UpdateEnvironmentGroupEnvironments	그룹과 연관된 환경 업데이트	0.1.0
	업데이트 환경 그룹 태그	그룹과 관련된 태그 업데이트	0.1.0
액세스 그룹(엔드포인트 그룹)
	목록 액세스 그룹	사용 가능한 모든 액세스 그룹 나열	0.1.0
	CreateAccessGroup	새로운 액세스 그룹을 만듭니다	0.1.0
	UpdateAccessGroupName	액세스 그룹 이름 업데이트	0.1.0
	UpdateAccessGroupUserAccesses	액세스 그룹에 대한 사용자 액세스 업데이트	0.1.0
	UpdateAccessGroupTeamAccesses	액세스 그룹에 대한 팀 액세스 업데이트	0.1.0
	AddEnvironmentToAccessGroup	액세스 그룹에 환경 추가	0.1.0
	액세스 그룹에서 환경 제거	액세스 그룹에서 환경 제거	0.1.0
스택(에지 스택)
	리스트스택	사용 가능한 모든 스택 나열	0.1.0
	스택파일 가져오기	특정 스택에 대한 compose 파일을 가져옵니다.	0.1.0
	크리에이트스택	새로운 Docker 스택을 만듭니다	0.1.0
	업데이트스택	기존 Docker 스택 업데이트	0.1.0
태그
	ListEnvironmentTags	사용 가능한 모든 환경 태그를 나열합니다.	0.1.0
	환경 태그 생성	새로운 환경 태그를 만듭니다	0.1.0
팀
	팀 목록	사용 가능한 모든 팀을 나열하세요	0.1.0
	팀 만들기	새로운 팀을 만드세요	0.1.0
	팀 이름 업데이트	팀 이름 업데이트	0.1.0
	팀원 업데이트	팀 멤버들에게 업데이트하기	0.1.0
사용자
	사용자 목록	사용 가능한 모든 사용자 나열	0.1.0
	업데이트 사용자	기존 사용자 업데이트	0.1.0
	설정 가져오기	Portainer 인스턴스의 설정을 가져옵니다.	0.1.0
도커
	도커프록시	모든 Docker API 요청 프록시	0.2.0
쿠버네티스
	쿠버네티스 프록시	모든 Kubernetes API 요청 프록시	0.3.0

개발

코드 통계

저장소에는 cloc 도구를 사용하여 Go 소스 파일의 코드 줄 수 및 기타 지표를 계산하는 도우미 스크립트 cloc.sh 포함되어 있습니다. cloc 먼저 설치해야 할 수도 있습니다(예: sudo apt install cloc 또는 brew install cloc ).

저장소 루트에서 스크립트를 실행하여 기본 요약 출력을 확인하세요.

./cloc.sh

특정 메트릭을 검색하는 데 사용할 수 있는 플래그에 대한 자세한 내용은 cloc.sh 스크립트 내의 주석 헤더를 참조하세요.

토큰 카운팅

현재 도구 정의가 프롬프트에서 얼마나 많은 토큰을 소모하는지 추정하려면 제공된 Go 프로그램과 셸 스크립트를 사용하여 Anthropic API의 토큰 계산 엔드포인트를 쿼리할 수 있습니다.

1. 도구 JSON 생성:

먼저, token-count Go 프로그램을 사용하여 YAML 도구 정의를 Anthropic API에서 요구하는 JSON 형식으로 변환합니다. 저장소 루트에서 다음 명령어를 실행합니다.

# 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. Anthropic 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

스크립트는 제공된 도구에 대한 추정 토큰 수와 usage.input_tokens 필드 아래의 샘플 메시지를 포함하는 Anthropic API의 JSON 응답을 출력합니다.

이 프로세스는 언어 모델에 제공된 툴셋과 관련된 토큰 비용을 이해하는 데 도움이 됩니다.

Portainer MCP