Portainer MCP
OfficialOfficial Portainer MCP server: manage Docker, Kubernetes, and GitOps environments via the Portainer REST API.
Add to your client
Copy the config for your MCP client and paste it into its config file.
uvx --from "mcp-portainer~=2.42.0" mcp-portainerPaste into ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"portainer-mcp": {
"command": "uvx",
"args": [
"--from",
"mcp-portainer~=2.42.0",
"mcp-portainer"
],
"env": {
"PORTAINER_URL": "https://portainer.example.com",
"PORTAINER_API_KEY": "ptr_xxxxxxxxxxxxxxxx"
}
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf
Before you start
- A Portainer instance (CE or EE) with a matching minor version (e.g. Portainer 2.42.x with server 2.42.x)
- A Portainer API key generated under My Account -> Access tokens
- uv installed and available on PATH for the uvx/stdio path (see https://docs.astral.sh/uv/getting-started/installation/), or Docker for the container deployment
About Portainer MCP
Official MCP server for Portainer, generated from the Portainer OpenAPI spec via FastMCP. It exposes the Portainer REST API as MCP tools (list/inspect environments, manage GitOps workflows, troubleshoot Docker and Kubernetes resources) and can proxy requests to the underlying Docker and Kubernetes APIs of each environment. Runs locally via uvx (stdio), as a one-click Claude Desktop .mcpb bundle, or as a container over HTTP for team deployments.
Tools & capabilities (7)
BASE profile toolsServer identity and configuration operations from tags auth, system, status, settings, motd. Effectively required as most workflows assume these are present.
DOCKER profile toolsDocker workload operations on Portainer-managed environments, from tags docker, endpoints, stacks.
KUBERNETES profile toolsKubernetes workload operations including Helm releases, from tags kubernetes, helm, endpoints, stacks.
EDGE profile toolsPortainer Edge fleet management, from tags edge, edge_stacks, edge_jobs, edge_groups, edge_update_schedules, edge_configs.
ADMIN profile toolsPlatform administration (identity, registries, backups, RBAC) from tags users, teams, team_memberships, roles, ldap, license, backup, registries, endpoint_groups, policies, resource_controls, tags.
docker_proxyProxies requests to the underlying Docker API of a managed environment. Registered by default; can be disabled with PORTAINER_NO_PROXY=1, and rejects non-GET requests in read-only mode.
kubernetes_proxyProxies requests to the underlying Kubernetes API of a managed environment. Registered by default; can be disabled with PORTAINER_NO_PROXY=1, and rejects non-GET requests in read-only mode.
When to use it
- Explore and inspect Portainer-managed Docker and Kubernetes environments from an AI client
- Manage GitOps workflows and stacks across environments
- Troubleshoot Docker and Kubernetes resources, including proxying to the underlying Docker/K8s APIs
- Run an audit/inventory persona with PORTAINER_PROFILES=ALL and PORTAINER_READ_ONLY=1 that can see everything but mutate nothing
- Provide a shared, team-wide MCP endpoint where each user acts under their own Portainer identity
Security notes
Generate an API key in Portainer under My Account -> Access tokens before use. Set PORTAINER_TLS_VERIFY=0 only for self-signed TLS certificates. For the container/HTTP deployment, both the gate secret (PORTAINER_MCP_AUTH_TOKEN) and each user's Portainer API key are sent across the wire, so TLS is required: bring your own certificates, attest a TLS-terminating reverse proxy, or explicitly opt into plaintext via PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 (dangerous). Set PORTAINER_MCP_ALLOWED_HOSTS to the reachable hostname/IP or the DNS-rebinding allowlist 421-rejects the request. It is NOT recommended to expose this MCP server on the public internet; host it inside private infrastructure even behind a TLS proxy. Environment variable values are redacted by default.
Portainer MCP FAQ
Which server version should I use?
Match the MCP server's minor version to your Portainer instance's minor — e.g. server 2.42.x with Portainer 2.42.x. The major+minor tracks the Portainer API version the embedded spec targets.
How do I run it for a single user vs. a team?
For a single user, run it locally as a stdio process via uvx (or install the one-click .mcpb bundle in Claude Desktop). For a team, deploy the published container (portainer/portainer-mcp) over HTTPS: a shared gate secret (PORTAINER_MCP_AUTH_TOKEN) admits requests and each client forwards its own Portainer API key via the X-Portainer-API-Key header.
Why are so few tools exposed by default?
The Portainer spec has 400+ operations across 40+ tags, which is too noisy for MCP clients. The server uses a tag allowlist organized into profiles (default BASE,DOCKER,KUBERNETES). Use PORTAINER_PROFILES to enable more (e.g. EDGE, ADMIN), PORTAINER_TAGS_EXTRA to add orphan tags like observability or gitops, or PORTAINER_PROFILES=ALL to expose every operation.
Can I restrict it to read-only?
Yes. Set PORTAINER_READ_ONLY=1 to register only GET/HEAD operations; the proxy tools also reject non-GET requests at call time. Note a few POST read-shaped endpoints (e.g. some snapshot listings) are hidden in this mode by design.
Alternatives to Portainer MCP
Compare all alternatives →
GitHub's official server for repos, issues, PRs, and Actions — local Docker or hosted remote.
Official AWS Labs server that lets agents call any AWS API via the AWS CLI surface.
Bulk Kubernetes port forwarding with an MCP server that lets AI assistants forward services, inspect pods, and monitor traffic.
Compare Portainer MCP with: