Portainer MCP Server

Manage Portainer container environments through AI: list and configure environments, deploy stacks, manage users and teams, and proxy Docker/Kubernetes commands.

Developer Tools by Portainer API Key active

GitHub Docs

Overview

Portainer MCP is the official Model Context Protocol server from Portainer, connecting AI assistants directly to Portainer container management environments. It exposes Portainer's API to MCP clients like Claude Desktop, letting agents query infrastructure state and execute container operations using natural language. The server works against any Portainer instance and supports both Docker and Kubernetes endpoints through proxy tools.

Capabilities span environment administration (tags, user and team access), edge environment groups, access groups, edge stacks, local Docker Compose stacks, tags, teams, users, and direct Docker/Kubernetes API proxying. A read-only mode is available to restrict the server to safe GET operations, and a configurable tools.yaml file lets operators trim the exposed surface area. The project is open source under Portainer's GitHub org and ships pre-built binaries for Linux (amd64, arm64) and macOS (arm64).

Note: the server is still under active development, requires an administrator API token, and validates the Portainer version it connects to (compatibility check can be disabled). Local stack support was introduced in v0.7.0.

Tools

Tool	Description
`ListEnvironments`	List all Portainer environments (endpoints).
`UpdateEnvironmentTags`	Update the tags assigned to an environment.
`UpdateEnvironmentUserAccesses`	Update per-user access on an environment.
`UpdateEnvironmentTeamAccesses`	Update per-team access on an environment.
`ListEnvironmentGroups`	List edge environment groups.
`CreateEnvironmentGroup`	Create a new edge environment group.
`UpdateEnvironmentGroupName`	Rename an environment group.
`UpdateEnvironmentGroupEnvironments`	Change which environments belong to a group.
`UpdateEnvironmentGroupTags`	Update tags on an environment group.
`ListAccessGroups`	List endpoint access groups.
`CreateAccessGroup`	Create an endpoint access group.
`UpdateAccessGroupName`	Rename an access group.
`UpdateAccessGroupUserAccesses`	Update user permissions on an access group.
`UpdateAccessGroupTeamAccesses`	Update team permissions on an access group.
`AddEnvironmentToAccessGroup`	Add an environment to an access group.
`RemoveEnvironmentFromAccessGroup`	Remove an environment from an access group.
`ListStacks`	List edge stacks.
`GetStackFile`	Retrieve the compose/manifest file for an edge stack.
`CreateStack`	Create a new edge stack.
`UpdateStack`	Update an existing edge stack.
`ListEnvironmentTags`	List environment tags.
`CreateEnvironmentTag`	Create a new environment tag.
`ListTeams`	List Portainer teams.
`CreateTeam`	Create a new team.
`UpdateTeamName`	Rename a team.
`UpdateTeamMembers`	Update team membership.
`ListUsers`	List Portainer users.
`UpdateUser`	Update an existing user.
`GetSettings`	Retrieve Portainer instance settings.
`DockerProxy`	Proxy arbitrary Docker API requests through Portainer.
`KubernetesProxy`	Proxy arbitrary Kubernetes API requests through Portainer.
`getKubernetesResourceStripped`	Fetch a Kubernetes resource with non-essential fields stripped for compact LLM consumption.
`ListLocalStacks`	List local standalone Docker Compose stacks.
`GetLocalStackFile`	Get the compose file for a local stack.
`CreateLocalStack`	Create a local Docker Compose stack.
`UpdateLocalStack`	Update a local Docker Compose stack.
`StartLocalStack`	Start a local stack.
`StopLocalStack`	Stop a local stack.
`DeleteLocalStack`	Delete a local stack.

Setup Guide

Prerequisites

A running Portainer instance (the README pins a specific supported version, e.g. Portainer 2.31.2 for portainer-mcp v0.7.0)
An administrator API token from your Portainer instance
Linux (amd64/arm64) or macOS (arm64)

Install

Download the pre-built binary from the releases page, verify the checksum, extract, and place it on your PATH:

curl -Lo portainer-mcp.tar.gz \
  https://github.com/portainer/portainer-mcp/releases/download/v0.7.0/portainer-mcp-v0.7.0-darwin-arm64.tar.gz
tar -xzf portainer-mcp.tar.gz
chmod +x portainer-mcp

Claude Desktop configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "portainer": {
      "command": "/path/to/portainer-mcp",
      "args": [
        "-server", "[IP]:[PORT]",
        "-token", "[TOKEN]",
        "-tools", "/tmp/tools.yaml"
      ]
    }
  }
}

Replace [IP]:[PORT] with your Portainer host (e.g. portainer.example.com:9443) and [TOKEN] with your admin API token.

Useful flags

-read-only: restrict the server to read-only operations
-disable-version-check: bypass the Portainer version compatibility check
-tools: path to a YAML file overriding the default tool definitions

Use Cases

Ask an AI assistant to audit user and team access across all Portainer environments and tighten over-permissioned accounts.
Deploy or update an edge stack across a group of remote Docker hosts using a natural language description of the compose file.
Triage a misbehaving Kubernetes workload by proxying kubectl-style requests through Portainer and inspecting stripped resource views.
Manage local Docker Compose stacks (create, start, stop, delete) on a Portainer-managed host without leaving your AI chat.
Bulk-tag environments and create access groups when onboarding new teams or customers.

Example Prompts

"List all Portainer environments and show which ones are missing the production tag."
"Create a new edge stack called monitoring from this compose file and deploy it to the EU edge group."
"Through the Kubernetes proxy on environment 3, list all pods in the payments namespace that are not Running."
"Stop the local stack named staging-api and then redeploy it with the updated compose file."
"Add the user alice to the platform team and give that team admin access on environment 5."

Pros

Official server maintained under the portainer GitHub organization.
Broad coverage of the Portainer API: environments, edge stacks, local Compose stacks, users, teams, plus raw Docker and Kubernetes proxies.
Read-only mode and a customizable tools.yaml allow operators to constrain what the AI can do.
Distributed as a single static binary for Linux and macOS, no runtime dependencies.

Limitations

Marked as a work in progress; tool surface and behavior may change between releases.
Strict Portainer version pinning means each portainer-mcp release targets one Portainer version (override only with -disable-version-check).
Requires an administrator API token, which grants broad privileges if not paired with -read-only or a trimmed tools file.

Alternatives

jmrplens/portainer-mcp-enhanced: community fork claiming 98 tools covering the full Portainer API.
ginkida/portainer-mcp: community implementation focused on stack, container, volume, and network management.
Docker MCP server: direct Docker engine access without Portainer in front.