用途
Portainer MCP 是一个面向 Portainer 的 MCP 服务器，由 Portainer OpenAPI 规范通过 FastMCP 生成。它的目标是把 Portainer REST API 封装为 MCP 工具，供 LLM 或 MCP 客户端调用，从而完成容器管理与基础设施监控相关的操作。官方说明指出，Portainer MCP 已不再是用 LLM 配合 Portainer 的受支持方式；受支持的方式是 Portainer Command，面向 Portainer Business Edition 客户（包括免费的 3 节点许可）。本仓库仍按原样保留，供继续使用的人使用，但不提供支持、保修或 SLA，也不建议用于生产环境，未来可能被归档。
主要能力
该 MCP 服务器提供以下能力：列出并检查环境；管理 GitOps 工作流；排查 Docker 和 Kubernetes 资源；代理请求到各环境底层的 Docker 和 Kubernetes API。默认启用的能力包括：基础 Portainer 操作支持（设置、版本、环境等）、Docker 操作支持、Kubernetes 操作支持、Docker 与 Kubernetes 代理支持，以及对环境变量值进行脱敏（默认启用）。还可以按 profile 配置启用不同的工具集、通过指定额外标签扩大 API 覆盖、仅暴露只读能力、禁用代理能力、调整传输能力与 TLS 姿态，以及配置日志。
使用方式
使用前需先在 Portainer 的 My Account → Access tokens 中生成 API 密钥。支持多种部署场景：
- MCP bundle（一键安装）：从最新 release 获取对应平台的自包含 .mcpb bundle，双击安装，然后输入 Portainer URL 和 API 密钥。要求客户端支持 MCP bundles。
- 单用户（通过 uvx 的 stdio）：在本机以 stdio 进程运行并直连 Portainer 实例。需安装 uv 并确保其在 PATH 中。若 Portainer 使用自签名 TLS 证书，可设置 PORTAINER_TLS_VERIFY=0。文档给出用 Claude Code 注册的方式，其他客户端参考 docs/distribution/。
- 团队部署（容器）：将 MCP 服务器作为容器部署在自有基础设施内，用户从工作站通过 HTTPS 访问。共享密钥用于把守 MCP 服务器，同时每个客户端还需转发自己的 Portainer API 密钥，使每个用户以自己的 Portainer 身份行事。该模式要求声明传输姿态：自带 TLS 证书、证明有 TLS 终止反向代理，或明确选择明文。明文是刻意且有风险的选择。不建议将 MCP 服务器暴露在公网，即使位于 TLS 代理之后也应托管在私有基础设施内。
部署通用要求：设置 PORTAINER_MCP_ALLOWED_HOSTS 为用户访问 MCP 所用的主机名或 IP，否则 DNS 重绑定允许列表会以 421 拒绝请求；HTTP 模式下必须设置 PORTAINER_MCP_AUTH_TOKEN，作为分发给用户的前置共享密钥，客户端通过 Authorization 头发送它，它只负责放行请求，用户能做什么由其自身 Portainer API 密钥决定。例外情况：在拥有 Authorization 头的身份感知代理之后，改用 PORTAINER_MCP_TRUST_PROXY_AUTH=1。
使用自有 TLS 证书部署容器后连接客户端；使用反向代理时不要发布容器端口，只让代理能访问；PORTAINER_MCP_FORWARDED_ALLOW_IPS 应使用代理的稳定精确 IP；确保代理转发原始 Host 和 X-Forwarded-Proto: https 头。自带代理并在容器前设置 TLS 终止代理同理。不建议在可信私有网络部署之外使用。可用 PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 启动仅 HTTP 的服务器。若用户通过支持 MCP OAuth 流程的身份感知代理（例如 MCP 服务器模式下的 Pomerium）认证，代理自行签发访问令牌并拥有 Authorization 头，则声明 trust-proxy auth 姿态，而不设置 PORTAINER_MCP_AUTH_TOKEN；此时不配置门禁令牌，请求凭代理证明放行，且每个请求仍需在 X-Portainer-API-Key 中携带调用者自己的 Portainer API 密钥，可由代理按用户注入或由各客户端发送。若 MCP 服务器自行终止 TLS 而非代理终止，则设置 PORTAINER_MCP_TRUSTED_PROXY_AUTH_IPS=<proxy ip/cidr> 替代两条 TRUST_PROXY_TLS / FORWARDED_ALLOW_IPS 配置。完整姿态规则见 docs/configuration.md。
版本兼容
将 MCP 服务器的次版本与 Portainer 的次版本对齐，主+次版本跟踪内嵌规范所针对的 Portainer API 版本。关于版本策略详见 docs/versioning.md。
限制与支持
Portainer MCP 没有官方支持渠道。可以在 GitHub 上提交 issue，但提交并不使项目有义务响应、分类或修复。不存在受支持的 Portainer MCP 版本；它按原样提供且无保修。它面向评估、家庭实验室及其他非生产用途，不适用于业务、生产或任何在意正常运行时间、安全态势或数据完整性的环境。没有 SLA，不保证对问题作出响应，没有后续功能开发，也没有路线图承诺。运行它意味着选择自行支持。
