Portainer MCP

MCP server for Portainer, generated from the Portainer OpenAPI spec via FastMCP.

Overview

This MCP server exposes the Portainer REST API as MCP tools: list and inspect environments, manage GitOps workflows, troubleshoot Docker and Kubernetes resources. It also supports proxying requests to the underlying Docker and K8s APIs of each environment.

Match the MCP server's minor version to your Portainer instance's minor — e.g. MCP server 2.45.x with Portainer 2.45.x. See Version compatibility for details.

Intended use

Portainer MCP is intended for evaluation, homelabs, and other non-production use. It is not supported in business, production, or any other environment where uptime, security posture, or data integrity matter. There is no SLA, no guaranteed response to issues, no further feature development, and no roadmap commitment. If you run it, you are choosing to self-support.

For a supported way to use an LLM with Portainer, use Portainer Command (Business Edition, including the free 3-node license).

Getting started

The MCP server supports different deployment scenarios:

• execute it locally via uvx
• install it as a MCP bundle
• deploy it as a container

Use the uvx approach or the MCP bundle to explore the MCP capabilities locally and deploy it inside your infrastructure as a container for a team based deployment setup.

MCP bundle (one-click install)

A convenient way to try the MCP server locally. Your client must support MCP bundles:

1. Fetch the self-contained .mcpb bundle for your platform from the latest release
2. Double-click to install
3. Enter your Portainer URL and API key.

Single user (stdio via uvx)

The other way to test the MCP server locally. Runs as a stdio process on your machine and connects directly to the Portainer instance.

Register with 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

For other clients, see docs/distribution/.

Team deployment (container)

A way to have multiple users interacting with your Portainer instance via MCP. Deployed as a container inside your infrastructure, accessed by users from their workstations over HTTPS. A shared secret gates the MCP server and every client also forwards its own Portainer API key so that each user acts under their own Portainer identity.

See more info below about the different deployment scenarios. For any of these scenarios:

• Set PORTAINER_MCP_ALLOWED_HOSTS to the hostname or IP address that users will use to reach the MCP — otherwise the DNS-rebinding allowlist 421-rejects the request.
• PORTAINER_MCP_AUTH_TOKEN is required in HTTP mode. It's the shared front-gate secret you distribute to your users; their MCP client sends it via the Authorization header. It only admits the request — what each user can do is governed by their own Portainer API key. The one exception: behind an identity-aware proxy that owns the Authorization header, use PORTAINER_MCP_TRUST_PROXY_AUTH=1 instead (see Option D).

Option A - BYO certificates

Deploy the container to use your own set of TLS certificates:

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

Then connect your client:

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>"

Option B - TLS-terminated reverse proxy

BYO proxy and set up a TLS-terminated proxy in front of the container:

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

Then connect your client:

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

Option C - Plaintext HTTP

Use the PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 flag to start the server with HTTP only.

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

Then connect your client:

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>"

Option D - Identity-aware proxy (MCP OAuth)

If your users authenticate through an identity-aware proxy that speaks the MCP OAuth flow (such as Pomerium in MCP server mode), the proxy mints its own access token and owns the Authorization header. Declare the trust-proxy auth posture instead of PORTAINER_MCP_AUTH_TOKEN:

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

No gate token is configured: the request is admitted by proxy attestation (it must arrive from PORTAINER_MCP_FORWARDED_ALLOW_IPS — inherited as the trust boundary, * refuses to boot) and by the caller's validated Portainer key. If the MCP server terminates TLS itself instead of the proxy, set PORTAINER_MCP_TRUSTED_PROXY_AUTH_IPS=<proxy ip/cidr> in place of the two TRUST_PROXY_TLS/FORWARDED_ALLOW_IPS lines. See docs/configuration.md for the full posture rules.

Restricting and expanding the MCP server capabilities

The MCP server comes with the following capabilities enabled by default:

• Basic Portainer operation support (settings, version, environments...)
• Docker operation support
• Kubernetes operation support
• Docker and Kubernetes proxy support
• Redacting environment variables values (enabled by default)

For restricting or expanding this set of capabilities, see docs/profiles.md.

Version compatibility

Match the MCP server's minor to your Portainer minor. The major+minor tracks the Portainer API version the embedded spec targets.

For more information about the versioning policy, see docs/versioning.md.

Configuration

The MCP server exposes different capabilities such as:

• Enable different set of tools based on specific profile configuration
• Widen the API coverage by specifying extra tags to cover
• Expose only read-only capabilities
• Disable proxy capabilities
• Tuning the transport capabilities and configuring the TLS posture
• Logging configuration

For more information about the MCP server configuration, refer to docs/configuration.md.

Getting help

Portainer MCP has no official support channel. Issues may be filed on GitHub, but doing so does not create any obligation on the project to respond, triage, or fix them.

There is no supported version of Portainer MCP; it is provided as-is and without warranty.