Portainer-MCP
项目介绍
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助手和其他工具以安全和标准化的方式与您的容器化基础设施交互。
[!NOTE] 此工具设计用于特定版本的Portainer。如果您的Portainer版本不匹配支持的版本，您可以使用
--disable-version-check标志尝试连接。有关兼容版本，请参阅Portainer 版本支持，有关绕过版本检查的说明，请参阅禁用版本检查。
有关兼容性和可用功能的更多详细信息，请参阅支持的功能部分。
注意：此项目目前仍在开发中。
它当前设计为与Portainer管理员API令牌一起工作。
安装
您可以在最新发布页面下载适用于Linux（amd64，arm64）和macOS（arm64）的预构建二进制文件。在“资产”部分找到适合您操作系统的架构对应的存档文件。
下载存档：
通常可以从发布页面直接下载。或者，您可以使用curl。以下是一个针对macOS（ARM64）版本v0.2.0的例子：
# 示例针对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
（Linux AMD64二进制文件也在发布页面上提供。）
（可选但推荐）验证校验和：
首先，从发布页面下载相应的.md5校验和文件。
例如，针对macOS（ARM64）v0.2.0：
# 下载校验和文件（根据版本/架构调整）
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
（对于Linux，您可以使用md5sum -c <checksum_file_name>.md5）
如果验证命令输出“OK”，则文件完好无损。
解压存档：
# 根据下载的版本/操作系统/架构调整文件名
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”。如果文件不存在，将在该位置创建一个带有默认工具定义的文件。当使用具有受限写入权限的工作目录的AI助手（如Claude）时，可能需要按照上述说明修改此路径。
禁用版本检查
默认情况下，应用程序会验证您的Portainer服务器版本是否与支持的版本匹配，并且如果有不匹配的情况，将无法启动。如果您有一个没有对应Portainer MCP版本的Portainer服务器版本，您可以禁用此版本检查以尝试连接。
要禁用版本检查，在您的命令参数中添加-disable-version-check标志：
{
"mcpServers": {
"portainer": {
"command": "/path/to/portainer-mcp",
"args": [
"-server",
"[IP]:[PORT]",
"-token",
"[TOKEN]",
"-disable-version-check"
]
}
}
}
[!WARNING] 禁用版本检查可能会导致意外行为或API不兼容性，特别是当您的Portainer服务器版本与支持的版本差异较大时。工具可能部分工作或完全无法工作于不受支持的版本。
使用此标志时：
- 应用程序将在启动时跳过Portainer服务器版本验证
- 由于版本之间的API差异，某些功能可能无法正常工作
- 较新的Portainer版本可能有API更改，导致错误
- 较旧的Portainer版本可能缺少工具期望的API
此标志在以下情况下有用：
- 您正在运行尚未支持MCP的新版本Portainer
- 您正在运行较旧版本的Portainer并想尝试使用此工具
工具自定义
默认情况下，工具定义嵌入在二进制文件中。如果不存在，应用程序将在默认位置创建一个工具文件。
您可以通过指定自定义工具文件路径来定制工具定义，使用-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 |
| 0.4.0 | 2.29.2 |
| 0.4.1 | 2.29.2 |
| 0.5.0 | 2.30.0 |
| 0.6.0 | 2.31.2 |
[!NOTE] 如果您需要连接到不受支持的Portainer版本，可以使用
-disable-version-check标志绕过版本验证。有关更多详细信息和使用此功能的重要警告，请参阅禁用版本检查部分。
支持的功能
下表列出了当前（最新版本）通过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 | |
| 获取Kubernetes资源简化 | 代理GET Kubernetes API请求并自动剥离冗长的元数据字段 | 0.6.0 |
开发
代码统计
仓库包括一个辅助脚本cloc.sh，使用cloc工具计算Go源文件的代码行数和其他指标。您可能需要先安装cloc（例如，sudo apt install cloc或brew install cloc）。
从仓库根目录运行脚本以查看默认汇总输出：
./cloc.sh
有关可用标志的详细信息，请参阅cloc.sh脚本中的注释头部，以检索特定指标。
令牌计数
要估算当前工具定义在提示中消耗了多少令牌，您可以使用提供的Go程序和shell脚本来查询Anthropic API的令牌计数端点。
1. 生成工具JSON：
首先，使用token-count Go程序将您的YAML工具定义转换为Anthropic API所需的JSON格式。从仓库根目录运行：
# 如果您的YAML文件不同，请替换internal/tooldef/tools.yaml
# 替换.output/tools.json为您的输出路径
go run ./cmd/token-count -input internal/tooldef/tools.yaml -output .tmp/tools.json
此命令从指定的输入YAML文件读取工具定义，并将包含name、description和input_schema的工具JSON数组写入指定的输出文件。
2. 查询Anthropic API：
接下来，使用token.sh脚本将这些工具定义连同示例消息发送到Anthropic API。您需要一个Anthropic API密钥来进行此步骤。
# 确保已安装jq
# 替换sk-ant-xxxxxxxx为您的实际Anthropic API密钥
# 替换.tmp/tools.json为第1步生成的文件路径
./token.sh -k sk-ant-xxxxxxxx -i .tmp/tools.json
脚本将输出来自Anthropic API的JSON响应，其中包含提供的工具和示例消息下的usage.input_tokens字段的估计令牌计数。
此过程有助于了解提供给语言模型的工具集相关的令牌成本。