Portainer MCP

是否曾经希望可以简单地询问Portainer正在发生什么？

现在你可以了！Portainer MCP将您的AI助手直接连接到您的Portainer环境中。管理Portainer资源，如用户和环境，或者通过AI直接执行任何Docker或Kubernetes命令来深入探索。

概述

Portainer MCP是针对Portainer环境的模型上下文协议 (MCP) 的一个正在进行中的实现。该项目旨在提供一种标准化的方式，以将Portainer的容器管理能力与AI模型和其他服务连接起来。

MCP（模型上下文协议）是一个开放协议，它标准化了应用程序如何向大型语言模型（LLMs）提供上下文。类似于USB-C为设备连接外围设备提供了标准化方式一样，MCP为AI模型连接不同的数据源和工具提供了一种标准化方式。

该实现着重于通过MCP协议公开Portainer环境数据，允许AI助手及其他工具以安全且标准化的方式与您的容器化基础设施交互。

有关兼容性和可用功能的更多详细信息，请参阅Portainer版本支持 和 支持的功能 部分。

注意：此项目目前正在开发中。

当前设计用于配合Portainer管理员API令牌工作。

安装

您可以从最新发布页面下载适用于Linux (amd64) 和 macOS (arm64) 的预构建二进制文件。在“Assets”部分找到适合您操作系统和架构的存档。

下载存档：
通常可以直接从发布页面下载。或者，您可以使用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] 替换为您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 模型如何解释和决定使用这些工具。如果您不希望使用某些工具，甚至可以决定移除它们。

[!WARNING]
不要更改工具名称或参数定义（除了描述），因为这将阻止工具正确注册和正常工作。

只读模式

对于注重安全性的用户，应用程序可以以只读模式运行。这种模式确保只有读操作可用，完全防止对您的 Portainer 资源进行任何修改。

要启用只读模式，请在命令参数中添加 -read-only 标志：

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

当使用只读模式时：

• 仅提供读取工具（列表、获取）给 AI 模型
• 所有写入工具（创建、更新、删除）都不会加载
• 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

支持的功能

下表列出了当前（最新版本）通过 MCP 工具支持的操作：

资源	操作	描述	支持的版本
环境
	列出环境	列出所有可用环境	0.1.0
	更新环境标签	更新与环境关联的标签	0.1.0
	更新环境用户访问权限	更新环境的用户访问策略	0.1.0
	更新环境团队访问权限	更新环境的团队访问策略	0.1.0
环境组（边缘组）
	列出环境组	列出所有可用的环境组	0.1.0
	创建环境组	创建新的环境组	0.1.0
	更新环境组名称	更新环境组的名称	0.1.0
	更新环境组中的环境	更新与组关联的环境	0.1.0
	更新环境组标签	更新与组关联的标签	0.1.0
访问组（端点组）
	列出访问组	列出所有可用的访问组	0.1.0
	创建访问组	创建新的访问组	0.1.0
	更新访问组名称	更新访问组的名称	0.1.0
	更新访问组用户访问权限	更新访问组的用户访问权限	0.1.0
	更新访问组团队访问权限	更新访问组的团队访问权限	0.1.0
	将环境添加到访问组	将环境添加到访问组	0.1.0
	从访问组中移除环境	从访问组中移除环境	0.1.0
堆栈（边缘堆栈）
	列出堆栈	列出所有可用堆栈	0.1.0
	获取堆栈文件	获取特定堆栈的compose文件	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
	更新团队成员	更新团队成员	0.1.0
用户
	列出用户	列出所有可用用户	0.1.0
	更新用户	更新现有用户	0.1.0
	获取设置	获取Portainer实例的设置	0.1.0
Docker
	Docker代理	代理任何Docker API请求	0.2.0
Kubernetes
	Kubernetes代理	代理任何Kubernetes API请求	0.3.0

开发

代码统计

该仓库包含一个辅助脚本 cloc.sh，用于使用 cloc 工具计算Go源文件的代码行数和其他指标。您可能需要先安装 cloc（例如，通过 sudo apt install cloc 或 brew install cloc 命令）。

从仓库根目录运行脚本以查看默认摘要输出：

./cloc.sh

请参阅 cloc.sh 脚本中的注释头部，以获取有关可用标志的详细信息来检索特定指标。