Purpose
Portainer MCP is an MCP server for Portainer, generated from the Portainer OpenAPI specification via FastMCP. Its goal is to wrap the Portainer REST API as MCP tools for LLMs or MCP clients to call, thereby completing operations related to container management and infrastructure monitoring. The official documentation states that Portainer MCP is no longer a supported way to use an LLM with Portainer; the supported way is Portainer Command, intended for Portainer Business Edition customers (including the free 3-node license). This repository is still retained as-is for those who continue to use it, but no support, warranty, or SLA is provided, it is not recommended for production environments, and it may be archived in the future.
Main capabilities
This MCP server provides the following capabilities: list and inspect environments; manage GitOps workflows; troubleshoot Docker and Kubernetes resources; proxy requests to the underlying Docker and Kubernetes APIs of each environment. The capabilities enabled by default include: basic Portainer operation support (settings, version, environments, etc.), Docker operation support, Kubernetes operation support, Docker and Kubernetes proxy support, and masking environment variable values (enabled by default). It is also possible to enable different tool sets by profile configuration, expand API coverage by specifying additional tags, expose only read-only capabilities, disable proxy capabilities, adjust transport capabilities and TLS posture, and configure logging.
Usage
Before use, you must first generate an API key in Portainer under My Account → Access tokens. Multiple deployment scenarios are supported:
- MCP bundle (one-click installation): obtain the self-contained .mcpb bundle for the corresponding platform from the latest release, double-click to install, then enter the Portainer URL and API key. Requires the client to support MCP bundles.
- Single-user (stdio via uvx): run as a stdio process on the local machine and connect directly to the Portainer instance. Requires uv to be installed and ensured to be in PATH. If Portainer uses a self-signed TLS certificate, and PORTAINER_TLS_VERIFY=0 can be set. The documentation provides the method for registering with Claude Code; for other clients, refer to docs/distribution/.
- Team deployment (container): Deploy the MCP server as a container within your own infrastructure, and users access it from workstations over HTTPS. A shared secret is used to guard the MCP server, while each client also needs to forward its own Portainer API key, so that each user acts as their own Portainer identity. This mode requires declaring a transport posture: bring your own TLS certificate, prove there is a TLS-terminating reverse proxy, or explicitly choose plaintext. Plaintext is a deliberate and risky choice. It is not recommended to expose the MCP server to the public internet; even behind a TLS proxy, it should be hosted within private infrastructure.
General deployment requirements: set PORTAINER_MCP_ALLOWED_HOSTS to the hostname or IP that users use to access MCP, otherwise the DNS rebinding allowlist will reject requests with 421; in HTTP mode, PORTAINER_MCP_AUTH_TOKEN must be set as the front-line shared secret distributed to users, and clients send it via the Authorization header. It is only responsible for allowing requests through; what a user can do is determined by their own Portainer API key. Exception: behind an identity-aware proxy that has an Authorization header, use PORTAINER_MCP_TRUST_PROXY_AUTH=1 instead.
After deploying the container with your own TLS certificate, connect clients; when using a reverse proxy, do not publish the container port, only let the proxy access it; PORTAINER_MCP_FORWARDED_ALLOW_IPS should use the proxy's stable exact IP; ensure the proxy forwards the original Host and X-Forwarded-Proto: https headers. The same applies when bringing your own proxy and placing a TLS-terminating proxy in front of the container. It is not recommended to use this outside a trusted private network deployment. You can use PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 to start an HTTP-only server. If users authenticate through an identity-aware proxy that supports the MCP OAuth flow (for example, Pomerium in MCP server mode), and the proxy issues access tokens itself and owns the Authorization header, then declare the trust-proxy auth posture instead of setting PORTAINER_MCP_AUTH_TOKEN; in this case, do not configure a gatekeeping token, requests are allowed based on the proxy's proof, and each request still needs to carry the caller's own Portainer API key in X-Portainer-API-Key, which can be injected per user by the proxy or sent by each client. If the MCP server terminates TLS itself rather than the proxy terminating it, then set PORTAINER_MCP_TRUSTED_PROXY_AUTH_IPS=<proxy ip/cidr> instead of the two TRUST_PROXY_TLS / FORWARDED_ALLOW_IPS settings. See docs/configuration.md for the complete posture rules.
Version compatibility
Align the MCP server's minor version with Portainer's minor version; the major+minor version tracks the Portainer API version targeted by the embedded specification. See docs/versioning.md for the versioning policy.
Limitations and support
Portainer MCP has no official support channel. Issues can be filed on GitHub, but filing one does not obligate the project to respond, triage, or fix it. There is no supported Portainer MCP version; it is provided as-is and without warranty. It is intended for evaluation, home labs, and other non-production uses, and is not suitable for business, production, or any environment that cares about uptime, security posture, or data integrity. There is no SLA, no guarantee of a response to issues, no follow-up feature development, and no roadmap commitment. Running it means choosing to support yourself.
