home / mcp / portainer mcp server

Portainer MCP Server

Bridges AI assistants with Portainer to manage Docker environments, containers, stacks, and networks via MCP.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "caffeineflo-portainer-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-e",
        "PORTAINER_URL=https://portainer.example.com",
        "-e",
        "PORTAINER_API_KEY=ptr_your_key_here",
        "ghcr.io/caffeineflo/portainer-mcp:latest"
      ],
      "env": {
        "PORTAINER_URL": "https://portainer.example.com",
        "PORTAINER_API_KEY": "ptr_your_key_here",
        "PORTAINER_WRITE_ENABLED": "true"
      }
    }
  }
}

This MCP server acts as a bridge between AI assistants and your Portainer instance, letting you list, inspect, and manage Docker environments, containers, stacks, images, volumes, and networks through Portainer’s API. You can perform read operations by default and enable write actions when you need to deploy or modify resources.

How to use

Connect your MCP client to the Portainer MCP Server to start listing resources and, when enabled, performing actions. You can browse environments, containers, stacks, images, volumes, and networks, view container logs, and deploy new Docker Compose stacks. All write operations are disabled by default and must be explicitly enabled to prevent accidental changes.

How to install

Prerequisites: you need Docker or Node.js installed on the host where you’ll run the MCP server. You will also need a Portainer instance with an API key to authorize actions.

# Option 1: Run via Docker (recommended)
docker run --rm \
  -e PORTAINER_URL=https://portainer.example.com \
  -e PORTAINER_API_KEY=ptr_your_key_here \
  ghcr.io/caffeineflo/portainer-mcp:latest
```

```bash
# Option 2: Run with Node.js
pnpm install
pnpm build
PORTAINER_URL=https://portainer.example.com \
PORTAINER_API_KEY=ptr_your_key_here \
node dist/index.js

Additional setup and notes

Configuration involves providing your Portainer URL and API key to the MCP server. You can enable write operations by setting the PORTAINER_WRITE_ENABLED variable to true. The server supports both HTTP-based remote configuration and local runtime execution via Node.js.

Available tools

list_environments

List all Portainer environments (Docker endpoints) with their IDs and basic metadata.

list_containers

List containers within an environment, with an option to include stopped containers.

inspect_container

Retrieve detailed information about a specific container, including status and configuration.

container_logs

Fetch logs for a container, with tail and max line options.

list_stacks

List all Docker Compose stacks across environments, with optional environment filtering.

inspect_stack

Get detailed information about a stack, including the compose content.

list_images

List Docker images available in an environment.

list_volumes

List Docker volumes in an environment.

list_networks

List Docker networks in an environment.

container_action

Start, stop, restart, kill, or remove a container.

stack_action

Start, stop, or remove a stack.

create_stack

Deploy a new Docker Compose stack from compose content.

manage_image

Pull or remove a Docker image.

manage_volume

Create or remove a Docker volume.

manage_network

Create or remove a Docker network, with optional custom subnet.