Portainer MCP

Portainer MCP

Portainer MCP 服务通过 FastMCP 根据 Portainer OpenAPI 规范生成。

重要

Portainer MCP 已不再是将大模型与 Portainer 搭配使用的受支持方式。 受支持的产品是 Portainer Command，Portainer Business Edition 客户可用（包括免费的 3 节点许可证）。

此服务仍按现状提供，供希望继续使用它的用户使用，但不提供支持、保证或 SLA，且不建议用于生产环境。此代码库未来可能会归档。

概览

此 MCP 服务将 Portainer REST API 暴露为 MCP 工具：列出和检查环境、管理 GitOps 工作流，以及排查 Docker 和 Kubernetes 资源问题。它还支持将请求代理到各环境底层的 Docker 和 K8s API。

MCP 服务的次要版本应与 Portainer 实例的次要版本匹配，例如：MCP 服务 2.45.x 搭配 Portainer 2.45.x。详情请参阅版本兼容性。

预期用途

Portainer MCP 适用于评估、家庭实验室及其他非生产用途。它不受支持用于商业、生产或其他任何对运行时间、安全状况或数据完整性有要求的环境。它没有 SLA，不保证响应问题，不再开发新功能，也没有路线图承诺。如果选择运行它，就意味着需要自行提供支持。

如需以受支持的方式将大模型与 Portainer 搭配使用，请使用 Portainer Command（Business Edition，包括免费的 3 节点许可证）。

开始使用

MCP 服务支持不同的部署场景：

• 通过 uvx 在本地运行
• 将其安装为 MCP bundle
• 将其部署为容器

使用 uvx 或 MCP bundle 在本地探索 MCP 功能，并将其作为容器部署到基础设施中，以便团队使用。

说明

使用 MCP 之前，请先在 Portainer 的 我的账户 → 访问令牌 中生成 API 密钥，因为这两种方式都需要该密钥。

MCP bundle（一键安装）

在本地试用 MCP 服务的便捷方式。你的客户端必须支持 MCP bundles：

1. 从最新版本下载适用于你平台的独立 .mcpb bundle
2. 双击安装
3. 输入 Portainer URL 和 API 密钥。

单用户（通过 uvx 使用 stdio）

这是在本地测试 MCP 服务的另一种方式。它会在你的计算机上作为 stdio 进程运行，并直接连接到 Portainer 实例。

说明

必须安装 uv，且它必须在 PATH 中可用。 请参阅 uv 安装文档。

如果 Portainer 实例使用自签名 TLS 证书，请设置 PORTAINER_TLS_VERIFY=0。

在 Claude Code 中注册：

claude mcp add portainer \
  -e PORTAINER_URL=https://portainer.example.com \
  -e PORTAINER_API_KEY=ptr_xxxxxxxxxxxxxxxx \
  -- uvx --from "mcp-portainer~=2.45.0" mcp-portainer

对于其他客户端，请参阅 docs/distribution/。

团队部署（容器）

一种让多个用户通过 MCP 与你的 Portainer 实例交互的方式。在你的基础设施内部以 container 的形式部署，用户通过 HTTPS 从各自的工作站访问。共享密钥用于保护 MCP 服务，每个客户端还会转发自己的 Portainer API 密钥，因此每位用户都以自己的 Portainer 身份进行操作。

重要

共享密钥和每位用户的 Portainer API 密钥都会通过网络传输。容器部署要求你声明传输安全方案：提供自己的 TLS 证书、证明已配置 TLS 终止反向代理，或明确选择使用明文传输。

明文传输是有意为之且危险的选择——请参阅下面的三个选项。

不建议将此 MCP 服务暴露在公共互联网上。请将其托管在你的私有基础设施内部，即使位于 TLS 代理之后也一样。

下面将介绍不同的部署场景。对于以下任一场景：

• 将 PORTAINER_MCP_ALLOWED_HOSTS 设置为用户访问 MCP 时使用的主机名或 IP 地址，否则 DNS 重绑定允许列表会以 421 拒绝请求。
• HTTP 模式下必须设置 PORTAINER_MCP_AUTH_TOKEN。这是你分发给用户的共享入口密钥；他们的 MCP 客户端会通过 Authorization 标头发送该密钥。它只负责放行请求——每位用户可以执行的操作由其自己的 Portainer API 密钥决定。唯一例外：如果位于负责管理 Authorization 标头的身份感知代理之后，请改用 PORTAINER_MCP_TRUST_PROXY_AUTH=1（参见选项 D）。

选项 A - 自备证书

说明

如果使用自签名证书，服务器会发出警告。使用私有 CA 证书不会触发警告，但在这两种情况下，你都可能需要采取一些额外步骤，才能将 MCP 客户端配置为接受该证书。

部署容器以使用你自己的 TLS 证书：

TOKEN=$(openssl rand -hex 32)
docker run -d --name portainer-mcp -p 17717:17717 \
	-v /etc/portainer-mcp/tls:/tls:ro \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com:17717 \
	-e PORTAINER_MCP_TLS_CERT=/tls/cert.pem \
	-e PORTAINER_MCP_TLS_KEY=/tls/key.pem \
	portainer/portainer-mcp:2.45

然后连接你的客户端：

claude mcp add portainer --transport http https://mcp.example.com:17717/mcp \
  --header "Authorization: Bearer <gate-token>" \
  --header "X-Portainer-API-Key: <ptr_user_key>"

选项 B - TLS 终止反向代理

说明

在 MCP 容器前使用反向代理时，不要发布容器端口；只有代理应能访问该端口。

如果代理 IP 地址固定，请将其确切 IP 用于 PORTAINER_MCP_FORWARDED_ALLOW_IPS。

确保代理转发原始的 Host 和 X-Forwarded-Proto: https 标头。

自备代理，并在容器前配置 TLS 终止代理：

TOKEN=$(openssl rand -hex 32)
docker run -d --name portainer-mcp \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com \
	-e PORTAINER_MCP_TRUST_PROXY_TLS=1 \
	-e PORTAINER_MCP_FORWARDED_ALLOW_IPS=172.18.0.0/16 \
	portainer/portainer-mcp:2.45

然后连接你的客户端：

claude mcp add portainer --transport http https://mcp.example.com/mcp \
  --header "Authorization: Bearer <gate-token>" \
  --header "X-Portainer-API-Key: <ptr_user_key>"

选项 C - 明文 HTTP

警告

不建议在可信的私有网络部署之外使用此方式。

使用 PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 标志，以仅使用 HTTP 的方式启动服务器。

TOKEN=$(openssl rand -hex 32)
docker run -d --name portainer-mcp -p 17717:17717 \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com:17717 \
	-e PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 \
	portainer/portainer-mcp:2.45

然后连接你的客户端：

claude mcp add portainer --transport http http://mcp.example.com:17717/mcp \
  --header "Authorization: Bearer <gate-token>" \
  --header "X-Portainer-API-Key: <ptr_user_key>"

选项 D - 身份感知代理（MCP OAuth）

如果用户通过支持 MCP OAuth 流程的身份感知代理进行身份验证（例如，以 MCP 服务模式运行的 Pomerium），代理会签发自己的访问令牌，并负责管理Authorization 标头。请声明信任代理身份验证策略，而不是设置 PORTAINER_MCP_AUTH_TOKEN：

说明

规则与选项 B 相同：不要公开容器端口（只有代理可以访问），并确保代理转发原始的 Host 和 X-Forwarded-Proto: https 标头。

每个请求仍需在 X-Portainer-API-Key 中提供调用方自己的 Portainer API 密钥——让代理按用户注入该密钥，或让每个客户端自行发送。代理负责处理谁可以访问；Portainer 密钥决定他们可以执行哪些操作。

docker run -d --name portainer-mcp \
	-e PORTAINER_URL=https://portainer.example.com \
	-e PORTAINER_MCP_TRUST_PROXY_AUTH=1 \
	-e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com \
	-e PORTAINER_MCP_TRUST_PROXY_TLS=1 \
	-e PORTAINER_MCP_FORWARDED_ALLOW_IPS=172.18.0.0/16 \
	portainer/portainer-mcp:2.45

未配置门控令牌：请求通过代理证明（必须来自 PORTAINER_MCP_FORWARDED_ALLOW_IPS——该变量继承为信任边界，设置为 * 会拒绝启动）以及调用方经过验证的 Portainer 密钥获得准入。如果 MCP 服务自行终止 TLS，而不是由代理终止，请设置 PORTAINER_MCP_TRUSTED_PROXY_AUTH_IPS=<proxy ip/cidr>，替代 TRUST_PROXY_TLS 和 FORWARDED_ALLOW_IPS 两行。完整策略规则请参阅 docs/configuration.md。

限制和扩展 MCP 服务的功能

MCP 服务默认启用以下功能：

• 基本 Portainer 操作支持（设置、版本、环境等）
• Docker 操作支持
• Kubernetes 操作支持
• Docker 和 Kubernetes 代理支持
• 对环境变量值进行脱敏（默认启用）

如需限制或扩展这些功能，请参阅 docs/profiles.md。

版本兼容性

MCP 服务的次版本号应与 Portainer 的次版本号一致。 主版本号和次版本号对应嵌入式规范所面向的 Portainer API 版本。

服务版本	Portainer（CE / EE）
2.45.x	2.45.x
2.44.x	2.44.x
2.43.x	2.43.x
2.42.x	2.42.x
2.41.x	2.41.x

有关版本策略的更多信息，请参阅 docs/versioning.md。

配置

MCP 服务提供多种功能，例如：

• 根据特定配置文件启用不同工具集
• 指定要涵盖的额外标签，以扩大 API 覆盖范围
• 仅开放只读功能
• 禁用代理功能
• 调整传输功能并配置 TLS 策略
• 日志配置

有关 MCP 服务配置的更多信息，请参阅 docs/configuration.md。

获取帮助

Portainer MCP 没有官方支持渠道。可以在 GitHub 上提交问题，但这并不意味着项目有义务回复、分类处理或修复问题。

Portainer MCP 没有受支持的版本；它按原样提供，不提供任何保证。