Portainer MCP

入口MCP

你有没有希望你能问问波蒂纳发生了什么事？

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

概述

Portainer MCP是正在进行中的 模型上下文协议（MCP） 适用于Portainer环境。该项目旨在提供一种标准化的方式，将Portainer的容器管理功能与人工智能模型和其他服务连接起来。

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

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

\[！注意\]

请参阅 支持的功能 有关兼容性和可用功能的更多详细信息，请参阅第节。

*注：该项目目前正在开发中。*

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

安装

您可以从以下网址下载Linux（amd64、arm64）和macOS（arm64）的预构建二进制文件 最新发布页面。在“资产”部分找到适合您的操作系统和体系结构的存档。

下载存档： 您通常可以直接从发布页面下载。或者，您可以使用 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 .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访问令牌。

\[！注意\] 默认情况下，该工具在与二进制文件相同的目录中查找“tools.yaml”。如果文件不存在，则将使用默认工具定义在那里创建它。您可能需要如上所述修改此路径，特别是在使用像Claude这样对工作目录具有受限写入权限的AI助手时。

禁用版本检查

默认情况下，应用程序会验证您的Portainer服务器版本是否与支持的版本匹配，如果不匹配，将无法启动。如果您的Portainer服务器版本没有相应的可用Portainer MCP版本，您可以禁用此版本检查以尝试连接。

要禁用版本检查，请添加 -disable-version-check 标记您的命令参数：

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

\[！警告\] 如果您的Portainer服务器版本与支持的版本存在显著差异，禁用版本检查可能会导致意外行为或API不兼容。该工具可能在不受支持的版本下部分工作或根本不工作。

使用此标志时：

• 应用程序将在启动时跳过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模型解释和决定使用它们的方式。如果你不想使用一些工具，你甚至可以决定删除它们。

\[！警告\] 不要更改工具名称或参数定义（描述除外），因为这将阻止工具正确注册和正常运行。

只读模式

对于有安全意识的用户，应用程序可以在只读模式下运行。此模式确保只有读取操作可用，完全防止对Portainer资源进行任何修改。

要启用只读模式，请添加 -read-only 标记您的命令参数：

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

使用只读模式时：

• 只有读取工具（列表、获取）可用于AI模型
• 未加载所有写入工具（创建、更新、删除）
• Docker和Kubernetes代理工具可用，但仅限于GET请求

Portainer版本支持

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

\[！注意\] 如果您需要连接到不受支持的Portainer版本，可以使用 -disable-version-check 标记以绕过版本验证。请参阅 禁用版本检查 有关使用此功能的更多详细信息和重要警告，请参阅第节。

支持的功能

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

\[！注意\] 边缘堆栈与本地堆栈：原始的Portainer MCP仅支持边缘堆栈（通过边缘组分发）。本地堆栈工具添加了对直接部署在环境中的常规独立Docker Compose堆栈的支持，这是非Edge设置中最常见的堆栈类型。自官方SDK以来，本地堆栈工具使用对Portainer REST API的原始HTTP请求(client-api-go)不公开常规堆栈端点。

发展

代码统计

存储库包含一个辅助脚本 cloc.sh 使用 cloc 工具。您可能需要安装 cloc 首先（例如。， sudo apt install cloc 或 brew install cloc).

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

./cloc.sh

请参阅 cloc.sh 用于检索特定指标的可用标志的详细信息的脚本。

令牌计数

为了估计当前工具定义在提示中消耗的令牌数量，可以使用提供的Go程序和shell脚本来查询Anthropic API的令牌计数端点。

1.生成工具JSON：

首先，使用 token-count 运行程序将您的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

该脚本将从Anthropic API输出JSON响应，其中包括所提供工具的估计令牌计数和 usage.input_tokens 现场。

此过程有助于理解与提供给语言模型的工具集相关的令牌成本。