Log inSubmit server
Portainer MCP logo

Portainer MCP

by portainer

Exposes Portainer, Docker, and Kubernetes management operations through MCP tools for non-production evaluation and homelabs.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Portainer MCP

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "portainer-portainer-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "mcp-portainer~=2.45.0",
        "mcp-portainer"
      ],
      "env": {
        "PORTAINER_URL": "YOUR_VALUE_HERE",
        "PORTAINER_API_KEY": "YOUR_VALUE_HERE",
        "PORTAINER_MCP_ALLOWED_HOSTS": "YOUR_VALUE_HERE",
        "PORTAINER_MCP_AUTH_TOKEN": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

portainer/portainer-mcp exposes the Portainer REST API through MCP tools generated from its OpenAPI specification with FastMCP. It can inspect environments, manage GitOps workflows, troubleshoot Docker and Kubernetes resources, and proxy requests to underlying environment APIs. Run it locally over stdio with uvx, install an MCP bundle, or deploy the container over HTTP for team access. Reach for it in evaluations and homelabs, not production, because the project is unsupported and requires matching its minor version to the Portainer instance.

Use cases

  • Inspect Portainer environments through an MCP client
  • Manage GitOps workflows with natural-language requests
  • Troubleshoot Docker and Kubernetes resources
  • Proxy environment API requests during homelab evaluation

Key features

  • Portainer REST API exposed as MCP tools
  • Environment listing and inspection
  • GitOps workflow management
  • Docker and Kubernetes troubleshooting
  • Docker and Kubernetes API proxying
  • stdio, MCP bundle, and container deployment modes

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

96/96 checks healthy over the last 25d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 1h ago via OSV.dev · mcp-portainer (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars239Stargazers on the source repository.
Last commit6d agoMost recent push to the default branch.
Directory activity9 viewsConfig copies, upvotes, and views on AllMCPs.

How Portainer MCP works

What portainer/portainer-mcp does

portainer/portainer-mcp turns Portainer's REST API into MCP tools for an AI client. The exposed operations cover environment discovery and inspection, GitOps workflow management, and troubleshooting for Docker and Kubernetes resources. It can also forward requests to the Docker and Kubernetes APIs associated with individual Portainer environments.

The implementation is generated from the Portainer OpenAPI specification using FastMCP. Its scope follows the permissions of the Portainer identity used for each request, making the Portainer API key an important part of the access model.

How it works

For local use, the server runs as a stdio process and connects directly to a Portainer instance. The documented uvx command starts the Python package and passes the Portainer URL and API key as environment variables. An MCP bundle provides another local installation path for clients that support MCP bundles.

For shared access, run the published container inside private infrastructure and expose its MCP endpoint over HTTPS. The container can terminate TLS itself, sit behind a TLS-terminating reverse proxy, or use plaintext HTTP when explicitly enabled for a trusted private network. HTTP deployments use a shared front-gate token, while each caller also supplies a Portainer API key so requests use that caller's Portainer identity. An identity-aware proxy can take ownership of the authorization header instead.

Match the server's minor version to the Portainer instance's minor version. For example, a 2.45.x server is intended for a 2.45.x Portainer instance.

Setup and configuration

Create an API key in Portainer under My Account → Access tokens before using the server. A local stdio setup needs PORTAINER_URL and PORTAINER_API_KEY. Self-signed Portainer certificates require PORTAINER_TLS_VERIFY=0.

Container-based HTTP deployments must define PORTAINER_MCP_ALLOWED_HOSTS; requests whose host is not allowed are rejected by the DNS-rebinding protection. They also require PORTAINER_MCP_AUTH_TOKEN, unless an identity-aware proxy is trusted with PORTAINER_MCP_TRUST_PROXY_AUTH=1. The MCP client sends the gate token in Authorization and the user's Portainer key in X-Portainer-API-Key.

When the container handles TLS, provide PORTAINER_MCP_TLS_CERT and PORTAINER_MCP_TLS_KEY. With a reverse proxy, enable PORTAINER_MCP_TRUST_PROXY_TLS=1 and restrict trusted proxy addresses with PORTAINER_MCP_FORWARDED_ALLOW_IPS. Plain HTTP requires the explicit PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 setting.

Tools and capabilities

  • List and inspect Portainer environments.
  • Manage GitOps workflows through Portainer.
  • Troubleshoot Docker resources.
  • Troubleshoot Kubernetes resources.
  • Proxy requests to an environment's Docker API.
  • Proxy requests to an environment's Kubernetes API.

Limitations and notes

Portainer no longer supports this project as its recommended LLM integration; Portainer Command is the supported alternative for Portainer Business Edition customers, including the free 3-node license. portainer/portainer-mcp is retained as-is without support, warranty, SLA, guaranteed issue response, planned feature development, or roadmap commitment.

Use it for evaluation, homelabs, and other non-production scenarios. The project is not recommended where uptime, security posture, or data integrity are important. Do not expose the container publicly; keep it in private infrastructure, including when placing it behind a TLS proxy. In HTTP mode, the shared gate secret and user Portainer keys travel over the connection, so the TLS and proxy posture must be configured deliberately.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Portainer MCP

portainer/portainer-mcp is an MCP server that connects AI clients to Portainer through its REST API. Its main tools list and inspect environments, manage GitOps workflows, troubleshoot Docker and Kubernetes resources, and proxy requests to the underlying Docker and Kubernetes APIs for each environment.

Install it locally with uvx, use the self-contained MCP bundle, or run the published container. Create a Portainer API key first, then configure the Portainer URL and credentials. MCP bundle installation requires a client that supports MCP bundles.

Run the container inside private infrastructure and expose its MCP endpoint over HTTPS. Set the allowed host and shared authentication token, then have each client send its user's Portainer API key. A TLS certificate, TLS-terminating reverse proxy, or explicitly enabled private-network plaintext mode is required.

Yes. Claude Code can register it as a stdio MCP server with the `claude mcp add` command, passing `PORTAINER_URL` and `PORTAINER_API_KEY` before launching it through uvx.

Use matching minor versions between the MCP server and Portainer. A 2.45.x MCP server is intended for a 2.45.x Portainer instance, so select the server version according to the Portainer minor version you run.

Related MCP servers

All in Cloud Platforms All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewPortainer MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/portainer-portainer-mcp?style=directory)](https://allmcps.com/mcp/portainer-portainer-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/portainer-portainer-mcp"><img src="https://allmcps.com/api/badge/portainer-portainer-mcp?style=directory" alt="Portainer MCP on AllMCPs" /></a>