Portainer MCP

是否曾希望可以直接向 Portainer 询问发生了什么？

概述

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

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

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

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

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

它目前被设计为与 Portainer 管理员 API 令牌一起使用。

安装

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

1. 下载存档。 您通常可以直接从发布页面下载。

   或者，您可以使用 curl。 以下是下载版本 v0.2.0 存档的示例：

   • Linux (AMD64):

     curl -Lo portainer-mcp-v0.2.0-linux-amd64.tar.gz https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-linux-amd64.tar.gz
     

   • macOS (ARM64):

     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
     

2. （可选但推荐）验证校验和。 首先，下载相应的 .md5 校验和文件。 使用 curl 和适当的 URL，替换 <VERSION>、<OS> 和 <ARCH>。

   • v0.2.0 在 Linux (AMD64) 上的示例：

     curl -Lo portainer-mcp-v0.2.0-linux-amd64.tar.gz.md5 https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-linux-amd64.tar.gz.md5
     # 现在验证
     md5sum -c portainer-mcp-v0.2.0-linux-amd64.tar.gz.md5
     

   • v0.2.0 在 macOS (ARM64) 上的示例：

     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
     # 现在验证（输出应与 .md5 文件的内容匹配）
     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
     

     如果验证命令输出“OK”，则文件完好无损。

3. 提取存档：

   tar -xzf portainer-mcp-v<VERSION>-<OS>-<ARCH>.tar.gz
   

   将 <VERSION>、<OS> 和 <ARCH> 替换为适当的值（例如，v0.2.0-linux-amd64）。 这将提取 portainer-mcp 可执行文件。

4. 将可执行文件移动到 $PATH 中的某个位置（例如，/usr/local/bin），或者记下其位置以供下面的配置步骤使用。

用法

使用 Claude Desktop，像这样配置它：

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

[!NOTE] 默认情况下，该工具在与二进制文件相同的目录中查找 "tools.yaml"。 您可能需要修改此路径，如上所述，尤其是在使用像 Claude 这样对工作目录具有受限写入权限的 AI 助手时。

将 [IP]、[PORT] 和 [TOKEN] 替换为与您的 Portainer 实例关联的 IP、端口和 API 访问令牌。

工具自定义

默认情况下，工具定义嵌入在二进制文件中。 如果默认位置尚不存在工具文件，则应用程序将在默认位置创建一个工具文件。

您可以通过使用 -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"
            ]
        }
    }
}

使用只读模式时：

• 只有读取工具（list、get）可供 AI 模型使用
• 所有写入工具（create、update、delete）都不会加载
• Docker 代理请求工具未加载

Portainer 版本支持

此工具被固定为支持特定版本的 Portainer。 应用程序将在启动时验证 Portainer 服务器版本，如果与所需的版本不匹配，则会失败。

Portainer MCP 版本	支持的 Portainer 版本
0.1.0	2.28.1
0.2.0	2.28.1

支持的功能

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

资源	操作	描述	支持的版本
环境
	ListEnvironments	列出所有可用的环境	0.1.0
	UpdateEnvironmentTags	更新与环境关联的标签	0.1.0
	UpdateEnvironmentUserAccesses	更新环境的用户访问策略	0.1.0
	UpdateEnvironmentTeamAccesses	更新环境的团队访问策略	0.1.0
环境组（Edge 组）
	ListEnvironmentGroups	列出所有可用的环境组	0.1.0
	CreateEnvironmentGroup	创建一个新的环境组	0.1.0
	UpdateEnvironmentGroupName	更新环境组的名称	0.1.0
	UpdateEnvironmentGroupEnvironments	更新与组关联的环境	0.1.0
	UpdateEnvironmentGroupTags	更新与组关联的标签	0.1.0
访问组（Endpoint 组）
	ListAccessGroups	列出所有可用的访问组	0.1.0
	CreateAccessGroup	创建一个新的访问组	0.1.0
	UpdateAccessGroupName	更新访问组的名称	0.1.0
	UpdateAccessGroupUserAccesses	更新访问组的用户访问权限	0.1.0
	UpdateAccessGroupTeamAccesses	更新访问组的团队访问权限	0.1.0
	AddEnvironmentToAccessGroup	将环境添加到访问组	0.1.0
	RemoveEnvironmentFromAccessGroup	从访问组中删除环境	0.1.0
堆栈（Edge 堆栈）
	ListStacks	列出所有可用的堆栈	0.1.0
	GetStackFile	获取特定堆栈的 compose 文件	0.1.0
	CreateStack	创建一个新的 Docker 堆栈	0.1.0
	UpdateStack	更新现有的 Docker 堆栈	0.1.0
标签
	ListEnvironmentTags	列出所有可用的环境标签	0.1.0
	CreateEnvironmentTag	创建一个新的环境标签	0.1.0
团队
	ListTeams	列出所有可用的团队	0.1.0
	CreateTeam	创建一个新的团队	0.1.0
	UpdateTeamName	更新团队的名称	0.1.0
	UpdateTeamMembers	更新团队的成员	0.1.0
用户
	ListUsers	列出所有可用的用户	0.1.0
	UpdateUser	更新现有用户	0.1.0
	GetSettings	获取 Portainer 实例的设置	0.1.0
Docker
	DockerProxy	代理任何 Docker API 请求	0.2.0

开发

代码统计

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

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

./cloc.sh

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