MIT License
Portainer MCP
Haben Sie sich jemals gewünscht, Sie könnten Portainer einfach fragen, was los ist?
Jetzt ist es möglich! Portainer MCP verbindet Ihren KI-Assistenten direkt mit Ihren Portainer-Umgebungen. Verwalten Sie Portainer-Ressourcen wie Benutzer und Umgebungen oder gehen Sie tiefer in die Materie, indem Sie beliebige Docker- oder Kubernetes-Befehle direkt über die KI ausführen.
Überblick
Portainer MCP ist eine in Arbeit befindliche Implementierung des Model Context Protocol (MCP) für Portainer-Umgebungen. Dieses Projekt zielt darauf ab, eine standardisierte Möglichkeit bereitzustellen, die Containerverwaltungsfunktionen von Portainer mit KI-Modellen und anderen Diensten zu verbinden.
MCP (Model Context Protocol) ist ein offenes Protokoll, das standardisiert, wie Anwendungen Kontext für LLMs (Large Language Models) bereitstellen. Ähnlich wie USB-C eine standardisierte Möglichkeit bietet, Geräte mit Peripheriegeräten zu verbinden, bietet MCP eine standardisierte Möglichkeit, KI-Modelle mit verschiedenen Datenquellen und Tools zu verbinden.
Bei dieser Implementierung liegt der Schwerpunkt auf der Bereitstellung von Portainer-Umgebungsdaten über das MCP-Protokoll, sodass KI-Assistenten und andere Tools auf sichere und standardisierte Weise mit Ihrer containerisierten Infrastruktur interagieren können.
Weitere Einzelheiten zur Kompatibilität und den verfügbaren Funktionen finden Sie in den Abschnitten „Versionsunterstützung“ und „Unterstützte Funktionen“ von Portainer.
Hinweis: Dieses Projekt befindet sich derzeit in der Entwicklung.
Es ist derzeit für die Verwendung mit einem Portainer-Administrator-API-Token ausgelegt.
Installation
Sie können vorgefertigte Binärdateien für Linux (amd64, arm64) und macOS (arm64) von der Seite „Neueste Version“ herunterladen. Das passende Archiv für Ihr Betriebssystem und Ihre Architektur finden Sie im Abschnitt „Assets“.
Archiv herunterladen: Normalerweise können Sie es direkt von der Release-Seite herunterladen. Alternativ können Sie curl verwenden. Hier ist ein Beispiel für macOS (ARM64) Version 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-Binärdateien sind auch auf der Release-Seite verfügbar.)
(Optional, aber empfohlen) Überprüfen Sie die Prüfsumme: Laden Sie zunächst die entsprechende .md5 Prüfsummendatei von der Release-Seite herunter. Beispiel für 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
(Unter Linux können Sie md5sum -c <checksum_file_name>.md5 verwenden.) Wenn der Überprüfungsbefehl „OK“ ausgibt, ist die Datei intakt.
Extrahieren Sie das Archiv:
# Adjust the filename based on the downloaded version/OS/architecture
tar -xzf portainer-mcp-v0.2.0-darwin-arm64.tar.gz
Dadurch wird die ausführbare Datei portainer-mcp extrahiert.
Verschieben Sie die ausführbare Datei: Verschieben Sie die ausführbare Datei an einen Speicherort in Ihrem $PATH (z. B. /usr/local/bin ) oder notieren Sie sich ihren Speicherort für den folgenden Konfigurationsschritt.
Verwendung
Konfigurieren Sie Claude Desktop folgendermaßen:
{
"mcpServers": {
"portainer": {
"command": "/path/to/portainer-mcp",
"args": [
"-server",
"[IP]:[PORT]",
"-token",
"[TOKEN]",
"-tools",
"/tmp/tools.yaml"
]
}
}
}
Ersetzen Sie [IP] , [PORT] und [TOKEN] durch die IP, den Port und das API-Zugriffstoken, die Ihrer Portainer-Instanz zugeordnet sind.
NOTE
Standardmäßig sucht das Tool im selben Verzeichnis wie die Binärdatei nach „tools.yaml“. Falls die Datei nicht vorhanden ist, wird sie dort mit den Standardtooldefinitionen erstellt. Möglicherweise müssen Sie diesen Pfad wie oben beschrieben ändern, insbesondere bei der Verwendung von KI-Assistenten wie Claude, die nur eingeschränkte Schreibberechtigungen für das Arbeitsverzeichnis haben.
Werkzeuganpassung
Standardmäßig sind die Tooldefinitionen in die Binärdatei eingebettet. Die Anwendung erstellt eine Tooldatei am Standardspeicherort, falls noch keine vorhanden ist.
Sie können die Tooldefinitionen anpassen, indem Sie mit dem Flag -tools einen benutzerdefinierten Tooldateipfad angeben:
{
"mcpServers": {
"portainer": {
"command": "/path/to/portainer-mcp",
"args": [
"-server",
"[IP]:[PORT]",
"-token",
"[TOKEN]",
"-tools",
"/path/to/custom/tools.yaml"
]
}
}
}
Die Standard-Tools-Datei steht im Quellcode unter internal/tooldef/tools.yaml zur Referenz bereit. Sie können die Beschreibungen der Tools und ihrer Parameter ändern, um die Interpretation und Verwendung durch KI-Modelle zu beeinflussen. Sie können sogar einige Tools entfernen, wenn Sie sie nicht verwenden möchten.
WARNING
Ändern Sie nicht die Toolnamen oder Parameterdefinitionen (mit Ausnahme der Beschreibungen), da dies dazu führt, dass die Tools nicht mehr richtig registriert werden und nicht mehr richtig funktionieren.
Schreibgeschützter Modus
Für sicherheitsbewusste Benutzer kann die Anwendung im schreibgeschützten Modus ausgeführt werden. Dieser Modus stellt sicher, dass nur Lesevorgänge verfügbar sind, wodurch Änderungen an Ihren Portainer-Ressourcen vollständig verhindert werden.
Um den schreibgeschützten Modus zu aktivieren, fügen Sie Ihren Befehlsargumenten das Flag -read-only hinzu:
{
"mcpServers": {
"portainer": {
"command": "/path/to/portainer-mcp",
"args": [
"-server",
"[IP]:[PORT]",
"-token",
"[TOKEN]",
"-read-only"
]
}
}
}
Bei Verwendung des schreibgeschützten Modus:
Dem KI-Modell stehen nur Lesetools (Liste, Abrufen) zur Verfügung.
Alle Schreibwerkzeuge (Erstellen, Aktualisieren, Löschen) werden nicht geladen
Das Docker-Proxy-Anforderungstool wird nicht geladen
Das Kubernetes-Proxy-Anforderungstool wird nicht geladen
Portainer-Versionsunterstützung
Dieses Tool unterstützt eine bestimmte Portainer-Version. Die Anwendung überprüft die Portainer-Serverversion beim Start und schlägt fehl, wenn sie nicht der erforderlichen Version entspricht.
Portainer MCP-Version | Unterstützte Portainer-Version |
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 |
Unterstützte Funktionen
In der folgenden Tabelle sind die derzeit (neueste Version) durch MCP-Tools unterstützten Vorgänge aufgeführt:
Ressource | Betrieb | Beschreibung | Unterstützt in Version |
Umgebungen | |||
Umgebungen auflisten | Alle verfügbaren Umgebungen auflisten | 0.1.0 | |
UpdateEnvironmentTags | Mit einer Umgebung verknüpfte Tags aktualisieren | 0.1.0 | |
UpdateEnvironmentUserAccesses | Aktualisieren der Benutzerzugriffsrichtlinien für eine Umgebung | 0.1.0 | |
UpdateEnvironmentTeamAccesses | Aktualisieren der Teamzugriffsrichtlinien für eine Umgebung | 0.1.0 | |
Umgebungsgruppen (Edge-Gruppen) | |||
Umgebungsgruppen auflisten | Auflisten aller verfügbaren Umgebungsgruppen | 0.1.0 | |
Umgebungsgruppe erstellen | Erstellen einer neuen Umgebungsgruppe | 0.1.0 | |
Umgebungsgruppenname aktualisieren | Aktualisieren des Namens einer Umgebungsgruppe | 0.1.0 | |
UpdateEnvironmentGroupEnvironments | Aktualisieren Sie Umgebungen, die einer Gruppe zugeordnet sind | 0.1.0 | |
UpdateEnvironmentGroupTags | Mit einer Gruppe verknüpfte Tags aktualisieren | 0.1.0 | |
Zugriffsgruppen (Endpunktgruppen) | |||
ListAccessGroups | Alle verfügbaren Zugriffsgruppen auflisten | 0.1.0 | |
Zugriffsgruppe erstellen | Erstellen einer neuen Zugriffsgruppe | 0.1.0 | |
Zugriffsgruppenname aktualisieren | Aktualisieren des Namens einer Zugriffsgruppe | 0.1.0 | |
UpdateAccessGroupUserAccesses | Aktualisieren von Benutzerzugriffen für eine Zugriffsgruppe | 0.1.0 | |
UpdateAccessGroupTeamAccesses | Teamzugriffe für eine Zugriffsgruppe aktualisieren | 0.1.0 | |
Umgebung zur Zugriffsgruppe hinzufügen | Hinzufügen einer Umgebung zu einer Zugriffsgruppe | 0.1.0 | |
Umgebung aus Zugriffsgruppe entfernen | Entfernen einer Umgebung aus einer Zugriffsgruppe | 0.1.0 | |
Stapel (Randstapel) | |||
ListStacks | Alle verfügbaren Stapel auflisten | 0.1.0 | |
GetStackFile | Holen Sie sich die Compose-Datei für einen bestimmten Stapel | 0.1.0 | |
Stapel erstellen | Erstellen Sie einen neuen Docker-Stack | 0.1.0 | |
UpdateStack | Aktualisieren eines vorhandenen Docker-Stacks | 0.1.0 | |
Schlagwörter | |||
ListEnvironmentTags | Listen Sie alle verfügbaren Umgebungs-Tags auf | 0.1.0 | |
UmgebungsTag erstellen | Erstellen eines neuen Umgebungstags | 0.1.0 | |
Teams | |||
ListTeams | Alle verfügbaren Teams auflisten | 0.1.0 | |
Team erstellen | Erstellen Sie ein neues Team | 0.1.0 | |
TeamName aktualisieren | Aktualisieren des Namens eines Teams | 0.1.0 | |
Teammitglieder aktualisieren | Aktualisieren der Mitglieder eines Teams | 0.1.0 | |
Benutzer | |||
Benutzerliste | Alle verfügbaren Benutzer auflisten | 0.1.0 | |
Benutzer aktualisieren | Aktualisieren eines vorhandenen Benutzers | 0.1.0 | |
Einstellungen abrufen | Holen Sie sich die Einstellungen der Portainer-Instanz | 0.1.0 | |
Docker | |||
DockerProxy | Proxy für alle Docker-API-Anfragen | 0.2.0 | |
Kubernetes | |||
KubernetesProxy | Proxy für alle Kubernetes-API-Anfragen | 0.3.0 |
Entwicklung
Code-Statistiken
Das Repository enthält das Hilfsskript cloc.sh zur Berechnung von Codezeilen und anderen Metriken für die Go-Quelldateien mithilfe des Tools cloc . Möglicherweise müssen Sie cloc zuerst installieren (z. B. sudo apt install cloc oder brew install cloc ).
Führen Sie das Skript vom Stammverzeichnis des Repositorys aus, um die standardmäßige Zusammenfassungsausgabe anzuzeigen:
./cloc.sh
Einzelheiten zu den verfügbaren Flags zum Abrufen bestimmter Metriken finden Sie in der Kommentarüberschrift im Skript cloc.sh
Token-Zählung
Um eine Schätzung zu erhalten, wie viele Token Ihre aktuellen Tooldefinitionen in Eingabeaufforderungen verbrauchen, können Sie das bereitgestellte Go-Programm und Shell-Skript verwenden, um den Token-Zählendpunkt der Anthropic API abzufragen.
1. Generieren Sie das Tools-JSON:
Verwenden Sie zunächst das Go-Programm token-count , um Ihre YAML-Tooldefinitionen in das von der Anthropic API benötigte JSON-Format zu konvertieren. Führen Sie Folgendes vom Repository-Stamm aus:
# 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
Dieser Befehl liest die Tooldefinitionen aus der angegebenen YAML-Eingabedatei und schreibt ein JSON-Array von Tools (mit name , description und input_schema ) in die angegebene Ausgabedatei.
2. Abfrage der Anthropic API:
Verwenden Sie anschließend das Skript token.sh , um diese Tooldefinitionen zusammen mit einer Beispielnachricht an die Anthropic API zu senden. Für diesen Schritt benötigen Sie einen Anthropic API-Schlüssel.
# 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
Das Skript gibt die JSON-Antwort der Anthropic-API aus, die die geschätzte Token-Anzahl für die bereitgestellten Tools und eine Beispielnachricht im Feld usage.input_tokens enthält.
Dieser Prozess hilft dabei, die Token-Kosten zu verstehen, die mit dem für das Sprachmodell bereitgestellten Toolset verbunden sind.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Portainer MCP
Related MCP Servers
- GPL 3.0
- MIT License