Portainer MCP

What portainer/portainer-mcp MCP server does

The portainer/portainer-mcp MCP server connects MCP clients to a Portainer instance and presents Portainer REST API operations as MCP tools. It covers basic Portainer functions such as reading settings, checking the Portainer version, and listing environments.

The server also supports operations involving Docker and Kubernetes resources. For environments managed through Portainer, it can proxy requests to the underlying Docker and Kubernetes APIs. GitOps workflows are included, as are operations intended to help investigate Docker and Kubernetes issues.

Capabilities enabled by default include core Portainer operations, Docker operations, Kubernetes operations, and Docker and Kubernetes proxy access. Environment variable values are redacted by default. Profiles can be used to restrict or expand the enabled capability set.

How it works

The portainer/portainer-mcp MCP server uses a Portainer API key to connect to the target Portainer URL. For local use, it runs as a stdio process on the user’s machine. In a team deployment, it runs in a container and clients connect over HTTP or HTTPS.

Local clients authenticate with the Portainer API key configured for the connection. In HTTP mode, the container also requires a shared front-gate token unless an identity-aware proxy is configured to handle authentication. Each user’s Portainer key determines the Portainer permissions applied to that user’s requests.

The MCP server’s minor version should match the Portainer instance’s minor version. For example, a 2.45.x MCP release is intended for a 2.45.x Portainer release.

Setup and configuration

The README documents three deployment paths:

• Run the server locally with uvx. The example uses mcp-portainer~=2.45.0 and requires uv on PATH.
• Install a platform-specific .mcpb MCP bundle from the latest release, then provide the Portainer URL and API key.
• Run the portainer/portainer-mcp container for shared team access.

The local stdio setup uses PORTAINER_URL and PORTAINER_API_KEY. Set PORTAINER_TLS_VERIFY=0 when the Portainer instance uses a self-signed TLS certificate.

Container deployments require an allowed host setting. HTTP mode also requires PORTAINER_MCP_AUTH_TOKEN, unless an identity-aware proxy is trusted instead. TLS can terminate in the container or at a reverse proxy. Plaintext HTTP is available only through an explicit opt-in and is documented for trusted private networks.

Tools and capabilities

The portainer/portainer-mcp MCP server supports tools for:

• Inspecting Portainer settings, version information, and environments
• Managing GitOps workflows
• Operating on Docker resources
• Operating on Kubernetes resources
• Troubleshooting Docker and Kubernetes resources
• Proxying requests to the Docker and Kubernetes APIs behind Portainer

Profiles provide configuration controls for limiting or expanding these capabilities. Environment variable redaction is enabled by default.

Limitations and notes

The server depends on a reachable Portainer instance and a valid API key. API compatibility requires matching the MCP and Portainer minor versions. Container deployments transmit the shared gate secret and user Portainer keys, so the README advises keeping the service inside private infrastructure rather than exposing it publicly.

When using a reverse proxy, the proxy must forward the original host and HTTPS scheme headers, and its network address must be declared where required. Clients may also need additional configuration to trust self-signed or privately issued certificates.