Portainer MCP Server

How to use

Install and run the Portainer MCP local proxy, then point your MCP client to the local process. Your AI assistant can list environments, groups, users, and other Portainer resources, update access policies, and proxy Docker and Kubernetes API calls through the MCP bridge. Use the provided configuration to enable read-only or full tool access as needed, and customize which tools you expose to your AI models.

How to install

Prerequisites: a Portainer instance with administrator API access, a compatible host to run the MCP binary, and basic command-line tools (curl and tar) available on your system.

# Step 1: Download the appropriate MCP binary for your OS and architecture from the release page
# Example for macOS (ARM64), version v0.2.0
curl -Lo portainer-mcp-v0.2.0-darwin-arm64.tar.gz https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-darwin-arm64.tar.gz

# Step 2: (Optional) Verify the checksum if you downloaded a checksum file
curl -Lo portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5 https://github.com/portainer/portainer-mcp/releases/download/v0.2.0/portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5
if [ "$(md5 -q portainer-mcp-v0.2.0-darwin-arm64.tar.gz)" = "$(cat portainer-mcp-v0.2.0-darwin-arm64.tar.gz.md5)" ]; then echo OK; else echo FAILED; fi

# Step 3: Extract the archive
tar -xzf portainer-mcp-v0.2.0-darwin-arm64.tar.gz

# Step 4: Move the executable to a directory in your PATH
sudo mv portainer-mcp /usr/local/bin/
``n

Additional setup and configuration

Configure your MCP client to connect to the Portainer MCP server by providing the path to the portainer-mcp binary and the required flags. The configuration below uses a local (stdio) setup. You can adjust the server IP, port, token, and the location for tools definitions as needed.

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

Security and run modes

You can enable a read-only mode to restrict actions to listing and getting resources. In read-only mode, write operations are disabled, and certain proxy tools are not loaded. This helps protect your Portainer environment when running AI-assisted workflows.

{
  "mcpServers": {
    "portainer": {
      "command": "/path/to/portainer-mcp",
      "args": [
        "-server",
        "[IP]:[PORT]",
        "-token",
        "[TOKEN]",
        "-read-only"
      ]
    }
  }
}

Version compatibility and notes

This tool validates the Portainer server version at startup to ensure compatibility. If your Portainer version is not directly supported, you can bypass version checks with a dedicated flag, but be aware of potential API incompatibilities and incomplete functionality.

Portainer MCP version support and capabilities

The MCP server exposes a comprehensive set of capabilities to manage Portainer resources and to proxy Docker and Kubernetes API requests. These include listing environments, managing access groups, stacks, users, and teams, and providing proxies for Docker and Kubernetes APIs.

Troubleshooting and notes

If you encounter startup failures, verify that the Portainer server URL, token, and version are correct. Ensure the MCP binary has the correct execute permissions and that the tools file path exists or will be created by the system when needed.

ListEnvironments

List all available environments in Portainer.

UpdateEnvironmentTags

Update tags associated with an environment.

UpdateEnvironmentUserAccesses

Update user access policies for an environment.

UpdateEnvironmentTeamAccesses

Update team access policies for an environment.

ListEnvironmentGroups

List all available environment groups.

CreateEnvironmentGroup

Create a new environment group.

UpdateEnvironmentGroupName

Update the name of an environment group.

UpdateEnvironmentGroupEnvironments

Update environments associated with a group.

UpdateEnvironmentGroupTags

Update tags associated with a group.

ListAccessGroups

List all available access groups.

CreateAccessGroup

Create a new access group.

UpdateAccessGroupName

Update the name of an access group.

UpdateAccessGroupUserAccesses

Update user accesses for an access group.

UpdateAccessGroupTeamAccesses

Update team accesses for an access group.

AddEnvironmentToAccessGroup

Add an environment to an access group.

RemoveEnvironmentFromAccessGroup

Remove an environment from an access group.

ListStacks

List all available stacks.

GetStackFile

Get the compose file for a specific stack.

CreateStack

Create a new Docker stack.

UpdateStack

Update an existing Docker stack.

ListEnvironmentTags

List all available environment tags.

CreateEnvironmentTag

Create a new environment tag.

ListTeams

List all available teams.

CreateTeam

Create a new team.

UpdateTeamName

Update the name of a team.

UpdateTeamMembers

Update the members of a team.

ListUsers

List all available users.

UpdateUser

Update an existing user.

GetSettings

Get the settings of the Portainer instance.

DockerProxy

Proxy ANY Docker API requests.

KubernetesProxy

Proxy ANY Kubernetes API requests.

getKubernetesResourceStripped

Proxy GET Kubernetes API requests and automatically strip verbose metadata fields.