LabscoMCP early access ↗
portainerMCP SERVER · OFFICIAL PROJECT

Portainer MCP

Inspect environments, drive GitOps workflows and troubleshoot Docker and Kubernetes from an MCP client — with the tool list scoped by profile.

by portainer ↗Containers, Kubernetes & Cluster Operations✓ Official

LABSCO SUMMARY

Decide what the agent may see before you decide what it may do.

Two switches carry most of the safety here. PORTAINER_PROFILES scopes which parts of Portainer exist at all — an Edge fleet operator never sees user administration — and PORTAINER_READ_ONLY registers only GET and HEAD operations, which also restricts the proxy tools. Together they make an audit persona that can see everything and change nothing. Two defaults worth knowing: environment values in stack and container responses are redacted unless you opt in, and responses are capped so a large listing degrades into a hint rather than blowing the client's output limit.

What it is

Portainer's official MCP server, generated from the Portainer OpenAPI spec. The spec holds more than 400 operations across more than 40 tags, which would be unusable as a flat tool list, so the server registers a named bundle of tags — a profile — and you decide which bundles to turn on.

What you get

  • BASE — server identity, login, settings and status; assumed present by most workflows
  • DOCKER — Docker workloads on managed environments: endpoints, stacks and GitOps sources
  • KUBERNETES — Kubernetes workloads including Helm releases, sharing endpoints and stacks with DOCKER
  • GITOPS — registering, listing and testing git sources and browsing refs, for a source-management-only role
  • EDGE — Portainer Edge fleet management: edge stacks, jobs, groups, configs and update schedules
  • ADMIN — platform administration: users, teams, roles, LDAP, licence, backup, registries, endpoint groups and resource controls
  • docker_proxy and kubernetes_proxy, escape hatches that pass a raw API call through when no generated tool fits
  • Tags that belong to no profile can be added individually with PORTAINER_TAGS_EXTRA — observability for container and pod logs, custom_templates, webhooks, useractivity and others
  • get_guidance serves the operating guide; the first call from a caller is answered with it before real work starts

Requirements

A Portainer instance at PORTAINER_URL, and a version match — the server's minor tracks the Portainer minor it was built against. Under stdio it carries one identity: PORTAINER_API_KEY, sent as X-API-KEY upstream. The container image runs HTTP instead, where each client presents two things — a shared gate secret in PORTAINER_MCP_AUTH_TOKEN, and its own Portainer key in an X-Portainer-API-Key header that is validated once and then forwarded, so users keep their own permissions. Over HTTP one TLS posture must be declared and the server refuses to start with none or both: either its own certificate through PORTAINER_MCP_TLS_CERT and PORTAINER_MCP_TLS_KEY, or a trusted terminating proxy through PORTAINER_MCP_TRUST_PROXY_TLS with PORTAINER_MCP_FORWARDED_ALLOW_IPS.

Setup effort

One command plus a key — uvx --from "mcp-portainer~=2.44.0" mcp-portainer, then supply credentials

See installation options