Skip to content
Back to search

portainer-mcp

Official Portainer MCP server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/portainer--portainer-mcp/badge.svg)](/listings/portainer--portainer-mcp)

HTML

<a href="/listings/portainer--portainer-mcp"><img src="/api/listings/portainer--portainer-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

> [!NOTE] > Before using the MCP, make sure to generate an API key in Portainer under **My Account → Access tokens** first as both paths need it.

MCP bundle (one-click install)

The recommended way to test the MCP server locally. Your client must support [MCP bundles](https://github.com/modelcontextprotocol/mcpb):

1. Fetch the self-contained `.mcpb` bundle for your platform from the [latest release](https://github.com/portainer/portainer-mcp/releases/latest) 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.

> [!NOTE] > `uv` must be installed and available on `PATH`. > See [the uv install docs](https://docs.astral.sh/uv/getting-started/installation/). > > Set `PORTAINER_TLS_VERIFY=0` if your Portainer instance uses self-signed TLS certificates.

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/`](https://github.com/portainer/portainer-mcp/tree/main/docs/distribution).

Team deployment (container)

The recommended way to have multiple users interacting with your Portainer instance via MCP. Deployed as a [`container`](https://hub.docker.com/r/portainer/portainer-mcp) 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.

> [!IMPORTANT] > Both the gate secret and each user Portainer API key are sent across the wire. The container deployment requires you to declare a transport posture: bring your own TLS certificates, attest a TLS-terminating reverse proxy setup or explicitly opt-in to plaintext. > > Plaintext is a deliberate, dangerous choice — see the three options below. > > It is **NOT** recommended to expose this MCP server on the public internet, host it inside your private infrastructure even behind a TLS proxy.

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

> [!NOTE] > The server will warn if using self-signed certificates. Using a private CA cert won't warn, but in both cases you will likely need to jump through some hoops to configure the MCP clients to accept it.

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:

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 224 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Portainer MCP
  2. MCP server for Portainer, generated from the Portainer OpenAPI spec via [FastMCP](https://github.com/PrefectHQ/fastmcp).
  3. > [!IMPORTANT]
  4. > **Portainer MCP is no longer the supported way to use an LLM with Portainer.** That is [Portainer Command](https://portainer.ai/products/portainer-command), available to Portainer Business Edition customers (including the free 3-node license).
  5. >
  6. > This server remains available as-is for people who want to keep using it, but it is provided without support, warranty or SLA, and is **not recommended for production environments**. This repository may be archived in the future.
  7. ## Overview
  8. 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.
  9. 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](#version-compatibility) for details.
  10. ## Intended use
  11. 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.
  12. For a supported way to use an LLM with Portainer, use [Portainer Command](https://portainer.ai/products/portainer-command) (Business Edition, including the free 3-node license).
  13. ## Getting started
  14. The MCP server supports different deployment scenarios:
  15. * execute it locally via `uvx`
  16. * install it as a MCP bundle
  17. * deploy it as a container
  18. 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.
  19. > [!NOTE]
  20. > Before using the MCP, make sure to generate an API key in Portainer under **My Account → Access tokens** first as both paths need it.
  21. ### MCP bundle (one-click install)
  22. A convenient way to try the MCP server locally. Your client must support [MCP bundles](https://github.com/modelcontextprotocol/mcpb):
  23. 1. Fetch the self-contained `.mcpb` bundle for your platform from the [latest release](https://github.com/portainer/portainer-mcp/releases/latest)
  24. 2. Double-click to install
  25. 3. Enter your Portainer URL and API key.
  26. ### Single user (stdio via `uvx`)
  27. The other way to test the MCP server locally. Runs as a stdio process on your machine and connects directly to the Portainer instance.
  28. > [!NOTE]
  29. > `uv` must be installed and available on `PATH`.
  30. > See [the uv install docs](https://docs.astral.sh/uv/getting-started/installation/).
  31. >
  32. > Set `PORTAINER_TLS_VERIFY=0` if your Portainer instance uses self-signed TLS certificates.
  33. Register with Claude Code:
  34. ````bash
  35. claude mcp add portainer \
  36. -e PORTAINER_URL=https://portainer.example.com \
  37. -e PORTAINER_API_KEY=ptr_xxxxxxxxxxxxxxxx \
  38. -- uvx --from "mcp-portainer~=2.45.0" mcp-portainer
  39. ````
  40. For other clients, see
  41. [`docs/distribution/`](https://github.com/portainer/portainer-mcp/tree/main/docs/distribution).
  42. ### Team deployment (container)
  43. A way to have multiple users interacting with your Portainer instance via MCP. Deployed as a [`container`](https://hub.docker.com/r/portainer/portainer-mcp) 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.
  44. > [!IMPORTANT]
  45. > Both the gate secret and each user Portainer API key are sent across the wire. The container deployment requires you to declare a transport posture: bring your own TLS certificates, attest a TLS-terminating reverse proxy setup or explicitly opt-in to plaintext.
  46. >
  47. > Plaintext is a deliberate, dangerous choice — see the three options below.
  48. >
  49. > It is **NOT** recommended to expose this MCP server on the public internet, host it inside your private infrastructure even behind a TLS proxy.
  50. See more info below about the different deployment scenarios. For any of these scenarios:
  51. * 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.
  52. * `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).
  53. #### Option A - BYO certificates
  54. > [!NOTE]
  55. > The server will warn if using self-signed certificates. Using a private CA cert won't warn, but in both cases you will likely need to jump through some hoops to configure the MCP clients to accept it.
  56. Deploy the container to use your own set of TLS certificates:
  57. ````bash
  58. TOKEN=$(openssl rand -hex 32)
  59. docker run -d --name portainer-mcp -p 17717:17717 \
  60. -v /etc/portainer-mcp/tls:/tls:ro \
  61. -e PORTAINER_URL=https://portainer.example.com \
  62. -e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
  63. -e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com:17717 \
  64. -e PORTAINER_MCP_TLS_CERT=/tls/cert.pem \
  65. -e PORTAINER_MCP_TLS_KEY=/tls/key.pem \
  66. portainer/portainer-mcp:2.45
  67. ````
  68. Then connect your client:
  69. ````bash
  70. claude mcp add portainer --transport http https://mcp.example.com:17717/mcp \
  71. --header "Authorization: Bearer <gate-token>" \
  72. --header "X-Portainer-API-Key: <ptr_user_key>"
  73. ````
  74. #### Option B - TLS-terminated reverse proxy
  75. > [!NOTE]
  76. > Don't publish the container port when using a reverse proxy in front of the MCP container, only the proxy should be able to reach it.
  77. >
  78. > Use your proxy exact IP if stable for `PORTAINER_MCP_FORWARDED_ALLOW_IPS`.
  79. >
  80. > Make sure that your proxy forwards the original `Host` and the `X-Forwarded-Proto: https` headers.
  81. BYO proxy and set up a TLS-terminated proxy in front of the container:
  82. ````bash
  83. TOKEN=$(openssl rand -hex 32)
  84. docker run -d --name portainer-mcp \
  85. -e PORTAINER_URL=https://portainer.example.com \
  86. -e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
  87. -e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com \
  88. -e PORTAINER_MCP_TRUST_PROXY_TLS=1 \
  89. -e PORTAINER_MCP_FORWARDED_ALLOW_IPS=172.18.0.0/16 \
  90. portainer/portainer-mcp:2.45
  91. ````
  92. Then connect your client:
  93. ````bash
  94. claude mcp add portainer --transport http https://mcp.example.com/mcp \
  95. --header "Authorization: Bearer <gate-token>" \
  96. --header "X-Portainer-API-Key: <ptr_user_key>"
  97. ````
  98. #### Option C - Plaintext HTTP
  99. > [!WARNING]
  100. > It is **NOT** recommended to use this outside of a trusted private network deployment.
  101. Use the `PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1` flag to start the server with HTTP only.
  102. ````bash
  103. TOKEN=$(openssl rand -hex 32)
  104. docker run -d --name portainer-mcp -p 17717:17717 \
  105. -e PORTAINER_URL=https://portainer.example.com \
  106. -e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \
  107. -e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com:17717 \
  108. -e PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 \
  109. portainer/portainer-mcp:2.45
  110. ````
  111. Then connect your client:
  112. ````bash
  113. claude mcp add portainer --transport http http://mcp.example.com:17717/mcp \
  114. --header "Authorization: Bearer <gate-token>" \
  115. --header "X-Portainer-API-Key: <ptr_user_key>"
  116. ````
  117. #### Option D - Identity-aware proxy (MCP OAuth)
  118. If your users authenticate through an identity-aware proxy that speaks the MCP OAuth flow (such as [Pomerium in MCP server mode](https://www.pomerium.com/docs/capabilities/mcp)), the proxy mints its own access token and **owns** the `Authorization` header. Declare the trust-proxy auth posture instead of `PORTAINER_MCP_AUTH_TOKEN`:
  119. > [!NOTE]
  120. > Same rules as Option B: don't publish the container port (only the proxy may reach it), and make sure the proxy forwards the original `Host` and `X-Forwarded-Proto: https` headers.
  121. >
  122. > Each request still needs the caller's own Portainer API key in `X-Portainer-API-Key` — have the proxy inject it per-user, or have each client send it. The proxy handles *who gets in*; the Portainer key governs *what they can do*.
  123. ````bash
  124. docker run -d --name portainer-mcp \
  125. -e PORTAINER_URL=https://portainer.example.com \
  126. -e PORTAINER_MCP_TRUST_PROXY_AUTH=1 \
  127. -e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com \
  128. -e PORTAINER_MCP_TRUST_PROXY_TLS=1 \
  129. -e PORTAINER_MCP_FORWARDED_ALLOW_IPS=172.18.0.0/16 \
  130. portainer/portainer-mcp:2.45
  131. ````
  132. 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`](https://github.com/portainer/portainer-mcp/blob/main/docs/configuration.md#auth-posture-identity-aware-proxies) for the full posture rules.
  133. ## Restricting and expanding the MCP server capabilities
  134. The MCP server comes with the following capabilities enabled by default:
  135. * Basic Portainer operation support (settings, version, environments...)
  136. * Docker operation support
  137. * Kubernetes operation support
  138. * Docker and Kubernetes proxy support
  139. * Redacting environment variables values (enabled by default)
  140. For restricting or expanding this set of capabilities, see [`docs/profiles.md`](https://github.com/portainer/portainer-mcp/blob/main/docs/profiles.md).
  141. ## Version compatibility
  142. **Match the MCP server's minor to your Portainer minor.** The major+minor tracks the Portainer API version the embedded spec targets.
  143. | Server version | Portainer (CE / EE) |
  144. | -------------- | ------------------- |
  145. | `2.45.x` | `2.45.x` |
  146. | `2.44.x` | `2.44.x` |
  147. | `2.43.x` | `2.43.x` |
  148. | `2.42.x` | `2.42.x` |
  149. | `2.41.x` | `2.41.x` |
  150. For more information about the versioning policy, see [`docs/versioning.md`](https://github.com/portainer/portainer-mcp/blob/main/docs/versioning.md).
  151. ## Configuration
  152. The MCP server exposes different capabilities such as:
  153. * Enable different set of tools based on specific profile configuration
  154. * Widen the API coverage by specifying extra tags to cover
  155. * Expose only read-only capabilities
  156. * Disable proxy capabilities
  157. * Tuning the transport capabilities and configuring the TLS posture
  158. * Logging configuration
  159. For more information about the MCP server configuration, refer to [`docs/configuration.md`](https://github.com/portainer/portainer-mcp/blob/main/docs/configuration.md).
  160. ## Getting help
  161. 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.
  162. There is no supported version of Portainer MCP; it is provided as-is and without warranty.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.