Skip to main content
Glama
portainer-mcp

portainer-mcp

by ginkida

Portainer MCP Server

License: MIT Python 3.10+ MCP PyPI

An MCP (Model Context Protocol) server that gives AI assistants — Claude, Copilot, Cursor, and others — 53 tools to manage Portainer container environments: deploy and update stacks (Env preserved, re-pull on demand), inspect Swarm services/tasks/nodes, manage containers/images/volumes/networks, exec commands, analyze logs, and inspect endpoints — all through natural language. Two optional Laravel helpers bring the total to 55.

For LLM agents: This server connects via stdio transport and ships server instructions (start with services on Swarm, inspect before update). Every tool returns JSON. All mutating operations are audit-logged. Credential-looking values are masked as [REDACTED] unless you ask for reveal_env=true. Credentials are passed via environment variables, never hardcoded.


Why Use This

  • Natural language DevOps — Ask your AI assistant to deploy a stack, check container logs, or pull an image.

  • Swarm-native — Services, tasks and nodes as first-class tools (docker service ls/ps/logs/update equivalents plus a per-stack health summary); stack deploys auto-detect Swarm vs standalone.

  • Safe by default — Input validation, path traversal protection, sensitive field filtering, credential masking in stack/service inspect, [REDACTED] values can never be written back, and force-remove disabled by default.

  • Token auth — Use a Portainer access token (PORTAINER_API_KEY) instead of an admin password.

  • Works everywhere — Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Continue.dev.


Related MCP server: VPS MCP Server

Quick Start

1. Install

pip install portainer-mcp

Or from source:

git clone https://github.com/ginkida/portainer-mcp.git
cd portainer-mcp
pip install -e .

2. Configure your AI client

Pick your client below, paste the config, and replace the placeholder values with your Portainer credentials.


Client Configuration

Claude Desktop

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "portainer": {
      "command": "python3",
      "args": ["-m", "portainer_mcp.server"],
      "env": {
        "PORTAINER_URL": "https://your-portainer:9443",
        "PORTAINER_API_KEY": "ptr_your-access-token",
        "PORTAINER_VERIFY_SSL": "false"
      }
    }
  }
}

PORTAINER_API_KEY is a Portainer access token (My account → Access tokens). You can use PORTAINER_USERNAME + PORTAINER_PASSWORD instead, as in the examples below.

Claude Code

File: .mcp.json in your project root (project-scope) or ~/.claude.json (user-scope)

{
  "mcpServers": {
    "portainer": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "portainer_mcp.server"],
      "env": {
        "PORTAINER_URL": "https://your-portainer:9443",
        "PORTAINER_USERNAME": "admin",
        "PORTAINER_PASSWORD": "${PORTAINER_PASSWORD}",
        "PORTAINER_VERIFY_SSL": "false"
      }
    }
  }
}

Or via CLI:

claude mcp add portainer -- python3 -m portainer_mcp.server

Cursor

File: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project)

{
  "mcpServers": {
    "portainer": {
      "command": "python3",
      "args": ["-m", "portainer_mcp.server"],
      "env": {
        "PORTAINER_URL": "https://your-portainer:9443",
        "PORTAINER_USERNAME": "admin",
        "PORTAINER_PASSWORD": "your-password",
        "PORTAINER_VERIFY_SSL": "false"
      }
    }
  }
}

Windsurf

File: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "portainer": {
      "command": "python3",
      "args": ["-m", "portainer_mcp.server"],
      "env": {
        "PORTAINER_URL": "https://your-portainer:9443",
        "PORTAINER_USERNAME": "admin",
        "PORTAINER_PASSWORD": "your-password",
        "PORTAINER_VERIFY_SSL": "false"
      }
    }
  }
}

VS Code (GitHub Copilot)

File: .vscode/mcp.json in your workspace

{
  "servers": {
    "portainer": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "portainer_mcp.server"],
      "env": {
        "PORTAINER_URL": "${input:portainer-url}",
        "PORTAINER_USERNAME": "${input:portainer-username}",
        "PORTAINER_PASSWORD": "${input:portainer-password}",
        "PORTAINER_VERIFY_SSL": "false"
      }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "portainer-url", "description": "Portainer base URL" },
    { "type": "promptString", "id": "portainer-username", "description": "Portainer username" },
    { "type": "promptString", "id": "portainer-password", "description": "Portainer password", "password": true }
  ]
}

Continue.dev

File: ~/.continue/config.yaml or .continue/config.yaml

mcpServers:
  - name: portainer
    type: stdio
    command: python3
    args:
      - -m
      - portainer_mcp.server
    env:
      PORTAINER_URL: "https://your-portainer:9443"
      PORTAINER_USERNAME: "admin"
      PORTAINER_PASSWORD: "your-password"
      PORTAINER_VERIFY_SSL: "false"

Environment Variables

Variable

Required

Default

Description

PORTAINER_URL

Yes

—

Portainer base URL, e.g. https://portainer.example.com:9443. Must be a root URL (no path). Plain http:// to a non-loopback host is allowed but logs a cleartext-credentials warning.

PORTAINER_API_KEY

One of

—

Portainer access token, sent as X-API-Key. Preferred: no admin password on disk, no JWT/CSRF handshake. Takes precedence over username/password.

PORTAINER_USERNAME

One of

—

Portainer username (with PORTAINER_PASSWORD; ignored when PORTAINER_API_KEY is set)

PORTAINER_PASSWORD

One of

—

Portainer password

PORTAINER_DEFAULT_ENDPOINT

No

1

Default endpoint ID for container/image/stack operations

PORTAINER_VERIFY_SSL

No

true

Set to false for self-signed certificates

PORTAINER_TIMEOUT

No

30

Timeout (seconds) for ordinary API calls

PORTAINER_LONG_TIMEOUT

No

300

Timeout (seconds) for long-running operations: image pull, container exec, large log scans

PORTAINER_HTTP_MAX_CONNECTIONS

No

100

Max concurrent HTTP connections to Portainer

PORTAINER_HTTP_MAX_KEEPALIVE

No

20

Max idle keep-alive connections

PORTAINER_JWT_TTL

No

25200 (7h)

Proactive JWT refresh interval (seconds). Set below Portainer's session timeout (default 8h) to avoid per-call 401 re-auth round-trips. Unused with PORTAINER_API_KEY.

PORTAINER_ENABLE_LARAVEL_TOOLS

No

false

Register the opinionated Laravel helpers (portainer_laravel_errors, portainer_laravel_tinker). Off by default — they assume a backend service with the app at /var/www/app.

All values are validated at startup — a malformed URL, a non-numeric timeout, or a non-positive limit fails fast with a clear error instead of breaking later.


Tools

All 53 tools are listed below with their parameters and descriptions (55 with the Laravel helpers enabled). Every tool returns JSON.

Authentication

Tool

Description

portainer_status()

Check connection and authentication status. Returns version, instance ID, auth mode, the number of endpoints and, for the default endpoint, its name/status and swarm (true only on a Swarm manager, where the service tools work) with swarm_role.

Endpoints (Environments)

Tool

Description

portainer_endpoints_list()

List all environments. Returns id, name, type, url, status.

portainer_endpoint_inspect(endpoint_id)

Get endpoint details (sensitive fields like TLS certs are filtered; the bulky raw DockerSnapshotRaw dump is dropped, the snapshot counters stay).

Stacks

Tool

Description

portainer_stacks_list()

List all stacks with id, name, type (swarm/compose), status, endpoint_id.

portainer_stack_inspect(stack_id, reveal_env?)

Get stack details, its Env variables and the compose file. Credential-looking values (*PASSWORD, *SECRET, *TOKEN, *KEY, DSNs, …) are masked as [REDACTED] unless reveal_env=true.

portainer_stack_deploy(name, compose_content, env?, endpoint_id?)

Deploy a new stack with optional Env variables. Auto-detects Swarm vs standalone.

portainer_stack_update(stack_id, compose_content?, env?, env_remove?, prune?, pull_image?, detach_from_git?, endpoint_id?)

Redeploy a stack. The stored Env variables are always preserved (Portainer replaces the whole list on every update; the tool reads it first and merges env / env_remove into it). prune defaults to the stack's current setting; pull_image=true is Portainer's "Re-pull image and redeploy" — required to roll out a new build of a :latest tag. A compose file containing [REDACTED] is rejected. A git-backed stack is refused unless detach_from_git=true (Portainer would silently drop the git link). endpoint_id is derived from the stack itself.

portainer_stack_status(stack_name, endpoint_id?)

Health summary: every service with running/desired replicas, update state and the task failures newer than its last good task. Cron-driven services (swarm-cronjob labels) are judged on their last run, not on replicas. Falls back to container states on a standalone endpoint (or for a Compose project on a manager).

portainer_stack_wait(stack_name, timeout_seconds?, endpoint_id?)

Poll stack_status after an update until every service is healthy, a rollout pauses on failure, or the timeout (default 120 s) elapses. Returns the final status plus converged / reason / timed_out.

portainer_stack_delete(stack_id, endpoint_id?)

Delete a stack (endpoint derived from the stack; a different endpoint_id is accepted only for an orphaned stack whose endpoint no longer exists).

portainer_stack_start(stack_id, endpoint_id?)

Start a stopped stack (endpoint derived from the stack).

portainer_stack_stop(stack_id, endpoint_id?)

Stop a running stack (endpoint derived from the stack).

Swarm

Tool

Description

portainer_services_list(endpoint_id?, stack_filter?)

docker service ls: every service with stack, image (tag and digest separated), mode, running/desired replicas, published ports and update status.

portainer_service_inspect(service_id, reveal_env?, endpoint_id?)

Full service definition (spec, previous spec, update status). Credential-looking Env values are masked unless reveal_env=true.

portainer_service_tasks(service_id, limit?, endpoint_id?)

docker service ps: tasks by slot with state, node hostname, container id and the scheduler / start error — the first place to look when replicas won't come up.

portainer_service_logs(service_id, tail?, since?, timestamps?, endpoint_id?)

Aggregated logs of all the service's tasks across nodes.

portainer_service_update(service_id, image?, replicas?, force_restart?, registry_id?, endpoint_id?)

docker service update: change the image, scale, or --force a restart (reads the current spec + version, submits it back). Pass image without a digest to make Swarm resolve the tag's current digest; force_restart alone re-creates tasks with the pinned digest. Portainer's stored registry credentials are used automatically when the image host matches a configured registry (or pass registry_id).

portainer_service_rollback(service_id, endpoint_id?)

docker service rollback: revert to the previous spec (requires a prior update).

portainer_service_wait(service_id, timeout_seconds?, endpoint_id?)

Poll until the service is healthy and its update finished, the update paused on failure, or the timeout elapses. Returns the service summary with converged / reason and recent task errors.

portainer_secrets_list(endpoint_id?)

Swarm secrets: names and metadata only, never values.

portainer_configs_list(endpoint_id?)

Swarm configs: names and metadata only, never content.

portainer_nodes_list(endpoint_id?)

Swarm nodes: hostname, role, availability, state, leader, engine version, CPUs/memory, labels.

Containers

Tool

Description

portainer_containers_list(endpoint_id?, show_all?, name_filter?, stack_filter?)

List containers with their stack and service (from Swarm/Compose labels). Set show_all=true to include stopped; name_filter applies a server-side Docker name filter; stack_filter keeps only one stack's containers.

portainer_container_inspect(container_id, endpoint_id?)

Get detailed container info.

portainer_container_start(container_id, endpoint_id?)

Start a stopped container.

portainer_container_stop(container_id, endpoint_id?)

Stop a running container.

portainer_container_restart(container_id, endpoint_id?)

Restart a container.

portainer_container_remove(container_id, force?, endpoint_id?)

Remove a container. force defaults to false.

portainer_container_logs(container_id, tail?, since?, timestamps?, endpoint_id?)

Get container logs as a JSON envelope (logs, truncated, total_chars). tail defaults to 100 (max 1000). since accepts a duration (10m, 2h, 1d), a Unix timestamp or an ISO-8601 datetime; timestamps=true prefixes each line.

portainer_container_logs_grep(container_id, pattern, tail?, context_lines?, since?, timestamps?, endpoint_id?)

Server-side regex over logs. Returns only matching lines (with optional context) — saves bandwidth on noisy logs.

portainer_container_stats(container_id, endpoint_id?)

Point-in-time CPU%, memory, network and block I/O stats (not a stream).

portainer_container_exec(container_id, command, workdir?, user?, endpoint_id?)

Run a shell command inside a running container and return its stdout/stderr + exit code. Audit-logged.

portainer_stack_logs_errors(stack_name, tail?, endpoint_id?)

Concurrent scan of every running container in a stack for HTTP 4xx/5xx, exceptions, fatal/critical levels, panics, OOM, PHP errors, etc.

Laravel (opt-in: PORTAINER_ENABLE_LARAVEL_TOOLS=true)

Tool

Description

portainer_laravel_errors(stack_name, tail?, endpoint_id?)

Read /var/www/app/storage/logs/laravel.log inside each container of a stack and return production.ERROR/CRITICAL/EMERGENCY entries — the actual exception behind a 500.

portainer_laravel_tinker(stack_name, code, endpoint_id?)

Execute PHP via php artisan tinker --execute=... in the first running {stack}_backend container (Swarm, plain-Compose and Compose-v1 naming all matched). Code capped at 4096 chars. Audit-logged.

Images

Tool

Description

portainer_images_list(endpoint_id?, reference_filter?)

List images with tags and sizes. reference_filter applies a server-side filter (e.g. nginx:1.25).

portainer_image_inspect(image_id, endpoint_id?)

Get detailed image info. Accepts name:tag or name@sha256:digest.

portainer_image_pull(image_name, tag?, registry_id?, registry_auth?, endpoint_id?)

Pull an image. tag defaults to "latest". For a registry configured in Portainer the stored credentials are supplied by Portainer itself — the registry is matched automatically by the image's host (reg.example.com/app → the Portainer registry with that URL; Docker Hub images match a DockerHub-type registry), or pass registry_id explicitly; registry_id=0 forces an anonymous pull (an explicit empty auth, so a stale stored token is bypassed); with several registries on the same host the pull stays anonymous and credentials names the candidate ids. A failed pull reports which credentials were used. No password passes through the model. The result reports registry_id and how credentials were chosen. registry_auth (base64 JSON {"username":..,"password":..,"serveraddress":..}) is only for registries Portainer doesn't know. The pull-progress stream is parsed and any errorDetail is surfaced as a tool error.

portainer_image_remove(image_id, endpoint_id?)

Remove an image.

portainer_registries_list()

Registries configured in Portainer (id, name, URL, type, authentication flag) — the registry_id source for pulls and service updates.

Volumes

Tool

Description

portainer_volumes_list(endpoint_id?, name_filter?)

List Docker volumes. name_filter applies a server-side name filter.

portainer_volume_inspect(volume_name, endpoint_id?)

Get detailed volume info.

portainer_volume_create(name, driver?, labels?, endpoint_id?)

Create a volume. driver defaults to "local".

portainer_volume_remove(volume_name, force?, endpoint_id?)

Remove a volume. force defaults to false.

Networks

Tool

Description

portainer_networks_list(endpoint_id?, name_filter?)

List Docker networks with driver, scope and attached container count. name_filter applies a server-side name filter.

portainer_network_inspect(network_id, endpoint_id?)

Get detailed network info.

portainer_network_create(name, driver?, internal?, labels?, endpoint_id?)

Create a network. driver defaults to "bridge" (use "overlay" for Swarm).

portainer_network_remove(network_id, endpoint_id?)

Remove a network.

portainer_network_connect(network_id, container_id, endpoint_id?)

Attach a container to a network.

portainer_network_disconnect(network_id, container_id, force?, endpoint_id?)

Detach a container from a network.

System

Tool

Description

portainer_docker_info(endpoint_id?)

OS, CPU, memory, container/image counts, swarm_active (node joined a Swarm) and swarm_manager.

portainer_docker_disk_usage(endpoint_id?)

Per-category disk usage (containers, images, volumes, build cache) with reclaimable size.

portainer_docker_prune(target, all_images?, endpoint_id?)

Reclaim disk: target is containers (stopped), images (dangling only, or all unused with all_images=true) or build_cache. Volumes are never pruned. Audit-logged.

Users

Tool

Description

portainer_users_list()

List all Portainer users with id, username, role.

portainer_user_inspect(user_id)

Get user details. Sensitive fields (password hash, TFA material, tokens) are filtered out.


Example Workflows

Deploy a new service:

"Deploy a stack called 'redis' with Redis 7 on port 6379"

The agent will call portainer_stack_deploy(name="redis", compose_content="...") with the generated compose YAML.

Debug a failing container:

"Why is the nginx container crashing?"

The agent will call portainer_containers_list() to find the container, then portainer_container_logs(container_id) to inspect the logs.

Roll out a new build on Swarm:

"Deploy the latest arena-etl image"

The agent will call portainer_stack_update(stack_id, pull_image=true) — the stack's Env variables are preserved — or portainer_service_update(service_id, image="registry/app:latest") for a single service, then portainer_stack_wait("arena-etl") to confirm the rollout converged (and portainer_service_rollback if it did not).

Update an existing stack:

"Update the arena-etl stack to use the new image tag v2.1"

The agent will call portainer_stack_inspect(stack_id, reveal_env=true) to get the current compose file, modify the image tag, then portainer_stack_update(stack_id, compose_content).

Why are replicas down?

"arena-etl_worker shows 0/2"

The agent will call portainer_service_tasks("arena-etl_worker") and read the task error (no suitable node, task: non-zero exit (137), image pull failures), then portainer_service_logs for the application side.


Security

  • Access-token auth (PORTAINER_API_KEY, sent as X-API-Key) — no admin password on disk, no session to refresh; Portainer skips CSRF checks for token requests. Falls back to JWT auth with proactive refresh (7h TTL, Portainer default is 8h), asyncio.Lock-guarded re-authentication for safe concurrent use, and 401/403-CSRF retry fallback.

  • CSRF handling for Portainer 2.39+ — Referer + X-CSRF-Token are sent only on mutating methods; CSRF token is harvested from X-CSRF-Token response headers and refreshed automatically.

  • SSL verification enabled by default. Only disable for self-signed certificates.

  • Input validation — container IDs, image references (incl. digests), stack names, volume/network names are regex-validated before any API call. Path traversal (..) is blocked.

  • Sensitive field filtering — endpoint_inspect strips TLS certificates, Azure credentials and security settings; user_inspect whitelists safe fields and hides password/TFA material; registries_list never returns registry credentials.

  • Credential masking — stack_inspect and service_inspect mask Env values whose name looks like a credential (and any user:pass@ inside URLs) as [REDACTED]; reveal_env=true shows them. A compose file or Env value containing [REDACTED] is refused by stack_update, so a masked value can never overwrite a real one. stack_update preserves the stack's stored Env on every redeploy.

  • Audit logging — every mutating operation (deploy, delete, remove, pull, start, stop, exec, tinker) is logged to stderr with parameters.

  • No hardcoded credentials — all secrets come from environment variables. Optional X-Registry-Auth for private-registry image pulls is passed in via parameter, never persisted.

  • Container removal — force defaults to false to prevent accidental deletion of running containers.

  • Log/exec size limits — output is capped at 100K characters to prevent memory exhaustion.

  • Non-JSON responses are surfaced, not swallowed — a reverse proxy's HTML login page in place of the API is reported as "Unexpected response from Portainer" with the content type and the first bytes of the body.


Development

git clone https://github.com/ginkida/portainer-mcp.git
cd portainer-mcp
pip install -e ".[dev]"

Run locally:

export PORTAINER_URL=https://your-portainer:9443
export PORTAINER_USERNAME=admin
export PORTAINER_PASSWORD=your-password
python3 -m portainer_mcp.server

Lint, type-check and test (CI runs the same on Python 3.10–3.13 for every push and pull request):

ruff check src/ tests/
mypy src/ tests/
pytest

Requirements

  • Python 3.10+

  • A running Portainer instance (CE or Business Edition)

  • Portainer API access (default port 9443)

License

MIT

Available Tools

53 tools
portainer_configs_listA

List Swarm configs (names and metadata only — never the content).

Args: endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: endpoint_id. Returns: result

portainer_container_execA

Execute a command inside a running container and return its output.

Args: container_id: Container ID or name command: Shell command to execute (run via sh -c) workdir: Working directory inside the container user: User to run the command as (e.g. 'root', '1000:1000') endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: command (required), container_id (required), user, workdir, +1 more. Returns: result

portainer_container_inspectA

Get detailed information about a container.

Args: container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: container_id (required), endpoint_id. Returns: result

portainer_container_logsA

Get container logs.

Args: container_id: Container ID or name tail: Number of lines from the end of the logs (default 100, max 1000) since: Only lines newer than this: a duration ("10m", "2h", "1d"), a Unix timestamp or an ISO-8601 datetime timestamps: Prefix every line with its timestamp (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: container_id (required), tail, since, timestamps, +1 more. Returns: result

portainer_container_logs_grepA

Search container logs for lines matching a regex pattern.

Returns only matching lines (with optional context). Useful for finding specific errors, status codes, or keywords without downloading the full log.

Args: container_id: Container ID or name pattern: Regex pattern to search for (case-insensitive) tail: Number of log lines to fetch before filtering (default 500, max 1000) context_lines: Lines of context around each match (default 0, max 5) since: Only scan lines newer than this: a duration ("10m", "2h", "1d"), a Unix timestamp or an ISO-8601 datetime timestamps: Prefix every line with its timestamp (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: pattern (required), container_id (required), tail, since, +3 more. Returns: result

portainer_container_removeA

Remove a container.

Args: container_id: Container ID or name force: Force removal of a running container (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: container_id (required), force, endpoint_id. Returns: result

portainer_container_restartB

Restart a container.

Args: container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: container_id (required), endpoint_id. Returns: result

portainer_containers_listA

List containers on an endpoint, with their stack and service.

On a Swarm endpoint prefer portainer_services_list / stack_status — containers there are task instances that come and go.

Args: endpoint_id: Target endpoint ID (uses default if omitted) show_all: If true, show all containers including stopped ones name_filter: Only return containers whose name contains this substring (server-side Docker filter) stack_filter: Only return containers belonging to this stack (Swarm namespace or Compose project label, exact match)

Inputs: show_all, endpoint_id, name_filter, stack_filter. Returns: result

portainer_container_startB

Start a stopped container.

Args: container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: container_id (required), endpoint_id. Returns: result

portainer_container_statsA

Get live CPU, memory, and network stats for a container.

Args: container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: container_id (required), endpoint_id. Returns: result

portainer_container_stopB

Stop a running container.

Args: container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: container_id (required), endpoint_id. Returns: result

portainer_docker_disk_usageA

Get Docker disk usage (containers, images, volumes, build cache).

Args: endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: endpoint_id. Returns: result

portainer_docker_infoA

Get Docker system information for an endpoint (OS, CPU, memory, containers count, etc).

Args: endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: endpoint_id. Returns: result

portainer_docker_pruneA

Reclaim disk space: remove stopped containers, unused images or build cache.

Volumes are never pruned by this tool (that destroys data); use portainer_volume_remove for a specific volume. Check portainer_docker_disk_usage first to see what is reclaimable.

Args: target: "containers" (all stopped), "images" (dangling only, or every unused image with all_images=true) or "build_cache" all_images: For target="images": also remove tagged images not used by any container (default false — dangling layers only) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: target (required), all_images, endpoint_id. Returns: result

portainer_endpoint_inspectC

Get details of a specific Portainer environment (endpoint).

Args: endpoint_id: The ID of the endpoint to inspect

Inputs: endpoint_id (required). Returns: result

portainer_endpoints_listB

List all Portainer environments (endpoints).

Inputs: no named parameters. Returns: result

portainer_image_inspectA

Get detailed information about a Docker image.

Args: image_id: Image ID or name:tag endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: image_id (required), endpoint_id. Returns: result

portainer_image_pullA

Pull a Docker image from a registry.

Credentials for a registry configured in Portainer are supplied by Portainer itself: the registry is picked automatically by matching the image's host against portainer_registries_list (Docker Hub images match a DockerHub-type registry), or explicitly via registry_id. registry_id=0 forces an anonymous pull. No password ever passes through the model. Explicit registry_auth is only needed for a registry Portainer does not know.

Args: image_name: Image name (e.g. 'nginx', 'ghcr.io/org/app') tag: Image tag (default 'latest') registry_id: ID of a registry configured in Portainer whose stored credentials should be used (auto-detected from the image host when omitted; 0 = pull anonymously) registry_auth: Base64-encoded JSON ({"username":..,"password":..,"serveraddress":..}) forwarded as X-Registry-Auth for a registry not configured in Portainer. Mutually exclusive with registry_id. endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: image_name (required), tag, endpoint_id, registry_id, +1 more. Returns: result

portainer_image_removeA

Remove a Docker image.

Args: image_id: Image ID or name:tag endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: image_id (required), endpoint_id. Returns: result

portainer_images_listA

List Docker images on an endpoint.

Args: endpoint_id: Target endpoint ID (uses default if omitted) reference_filter: Only return images matching this reference (e.g. 'nginx' or 'nginx:1.25'; server-side Docker filter)

Inputs: endpoint_id, reference_filter. Returns: result

portainer_network_connectB

Connect a container to a network.

Args: network_id: Network ID or name container_id: Container ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: network_id (required), container_id (required), endpoint_id. Returns: result

portainer_network_createA

Create a Docker network.

Args: name: Network name driver: Network driver (default 'bridge'; use 'overlay' for Swarm) internal: Restrict external access (default false) labels: Optional labels as key-value pairs endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: name (required), driver, labels, internal, +1 more. Returns: result

portainer_network_disconnectA

Disconnect a container from a network.

Args: network_id: Network ID or name container_id: Container ID or name force: Force disconnect (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: network_id (required), container_id (required), force, endpoint_id. Returns: result

portainer_network_inspectB

Get detailed information about a Docker network.

Args: network_id: Network ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: network_id (required), endpoint_id. Returns: result

portainer_network_removeA

Remove a Docker network.

Args: network_id: Network ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: network_id (required), endpoint_id. Returns: result

portainer_networks_listA

List Docker networks on an endpoint.

Args: endpoint_id: Target endpoint ID (uses default if omitted) name_filter: Only return networks whose name contains this substring (server-side Docker filter)

Inputs: endpoint_id, name_filter. Returns: result

portainer_nodes_listA

List Swarm nodes with role, availability, state and resources.

Args: endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: endpoint_id. Returns: result

portainer_registries_listA

List registries configured in Portainer (id, name, URL, type).

Use the id as registry_id in portainer_image_pull / portainer_service_update so Portainer supplies the stored credentials.

Inputs: no named parameters. Returns: result

portainer_secrets_listA

List Swarm secrets (names and metadata only — never the values).

Args: endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: endpoint_id. Returns: result

portainer_service_inspectA

Get the full Swarm service definition (spec, update status, endpoint).

Credential-looking environment values in the container spec are masked as [REDACTED] unless reveal_env=true.

Args: service_id: Service ID or name (e.g. "arena-etl_backend") reveal_env: Return credential values unmasked (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: service_id (required), reveal_env, endpoint_id. Returns: result

portainer_service_logsA

Get logs of a Swarm service (all its tasks, across nodes).

Args: service_id: Service ID or name tail: Number of lines from the end of the logs (default 100, max 1000) since: Only lines newer than this: a duration ("10m", "2h", "1d"), a Unix timestamp or an ISO-8601 datetime timestamps: Prefix every line with its timestamp (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: service_id (required), tail, since, timestamps, +1 more. Returns: result

portainer_service_rollbackA

Roll a Swarm service back to its previous spec (docker service rollback).

Works only while Swarm still holds a PreviousSpec (i.e. after at least one update). Follow up with portainer_service_wait.

Args: service_id: Service ID or name endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: service_id (required), endpoint_id. Returns: result

portainer_services_listA

List Swarm services with running/desired replica counts.

On a Swarm endpoint this is the primary view (like docker service ls): services are the stable units, containers are their tasks. Cron-driven services (swarm-cronjob) carry cron: true and their last run's outcome instead of a meaningful replica count.

Args: endpoint_id: Target endpoint ID (uses default if omitted) stack_filter: Only services of this stack (exact stack name)

Inputs: endpoint_id, stack_filter. Returns: result

portainer_service_tasksA

List a service's tasks with state, node and error (docker service ps).

The first place to look when replicas are not coming up: a task's error carries the scheduler / container start failure ("no suitable node", "task: non-zero exit (1)", image pull errors, ...).

Args: service_id: Service ID or name limit: Max tasks to return, newest per slot first (default 50, max 500) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: service_id (required), limit, endpoint_id. Returns: result

portainer_service_updateA

Update a Swarm service: change its image, scale it, or force a restart.

Reads the current spec and version, applies the requested changes and submits the spec back (rolling update per the service's UpdateConfig). At least one of image / replicas / force_restart is required. Follow up with portainer_service_wait to know when the rollout converged.

To roll out a new build of the same :latest tag, pass image= ":" without a digest — Swarm resolves the tag to its current digest at update time. force_restart alone re-creates the tasks with the image digest already pinned in the spec.

Args: service_id: Service ID or name image: New image reference (e.g. "registry.example.com/app:latest") replicas: New replica count (replicated services only) force_restart: Re-create all tasks even if the spec is unchanged (docker service update --force) registry_id: ID of a Portainer-configured registry whose stored credentials the nodes should use to pull the image (auto-detected from the image host when omitted; 0 = none) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: service_id (required), image, replicas, endpoint_id, +2 more. Returns: result

portainer_service_waitA

Wait for a service's rollout to converge after an update/rollback.

Polls until the service is healthy (running == desired and the update finished), the update paused on failure, or the timeout elapses. Returns the final service summary with converged, reason, timed_out and the recent task errors.

Args: service_id: Service ID or name timeout_seconds: How long to wait (default 120, clamped to 5..PORTAINER_LONG_TIMEOUT) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: service_id (required), endpoint_id, timeout_seconds. Returns: result

portainer_stack_deleteB

Delete a stack.

Args: stack_id: The ID of the stack to delete endpoint_id: Endpoint ID (derived from the stack itself if omitted)

Inputs: stack_id (required), endpoint_id. Returns: result

portainer_stack_deployA

Deploy a new stack from a docker-compose string.

Args: name: Name of the new stack compose_content: Docker Compose file content (YAML string) env: Stack environment variables (substituted into the compose file by Portainer), e.g. {"DB_PASSWORD": "..."} endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: name (required), compose_content (required), env, endpoint_id. Returns: result

portainer_stack_inspectA

Get details of a stack including its compose file content.

Credential-looking values (stack Env variables named like *PASSWORD, *SECRET, *TOKEN, *KEY, ... and inline environment values in the compose file) are masked as [REDACTED] unless reveal_env=true. Always inspect with reveal_env=true before resending the compose file through portainer_stack_update — a masked file is rejected.

Args: stack_id: The ID of the stack to inspect reveal_env: Return credential values unmasked (default false)

Inputs: stack_id (required), reveal_env. Returns: result

portainer_stack_logs_errorsA

Scan all running containers in a stack for errors.

Fetches logs from every running container whose name starts with the given stack name and filters for common error patterns: HTTP 4xx/5xx, exceptions, fatal/critical/emergency log levels, panics, OOM, PHP errors, segfaults, etc.

Args: stack_name: Stack name prefix (e.g. "taylor", "blog", "somnlyx") tail: Log lines per container to scan (default 500, max 1000) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: stack_name (required), tail, endpoint_id. Returns: result

portainer_stacks_listA

List all Portainer stacks.

Inputs: no named parameters. Returns: result

portainer_stack_startA

Start a stopped stack.

Args: stack_id: The ID of the stack to start endpoint_id: Endpoint ID (derived from the stack itself if omitted)

Inputs: stack_id (required), endpoint_id. Returns: result

portainer_stack_statusA

Health summary of a stack: every service with running/desired replicas, update state and the most recent task failures.

Start here when asked "is stack X ok / why is X down". Works on Swarm (services + tasks) and falls back to container states on a standalone Compose endpoint. Cron-driven services are judged on their last run, and only failures newer than the last good task are reported.

Args: stack_name: Stack name (Swarm namespace / Compose project) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: stack_name (required), endpoint_id. Returns: result

portainer_stack_stopB

Stop a running stack.

Args: stack_id: The ID of the stack to stop endpoint_id: Endpoint ID (derived from the stack itself if omitted)

Inputs: stack_id (required), endpoint_id. Returns: result

portainer_stack_updateA

Update (redeploy) an existing stack.

The stack's stored Env variables are always preserved: Portainer replaces the whole Env list on every update, so this tool reads the current list first and merges your changes into it. Omit every optional argument to simply redeploy the stack as it is.

To pick up a newly pushed build of a :latest image, pass pull_image=true — a plain redeploy reuses the image already on the nodes.

Args: stack_id: The ID of the stack to update compose_content: New Docker Compose content (YAML). If omitted, the stored file is redeployed unchanged. Must not contain [REDACTED] (inspect with reveal_env=true first). env: Env variables to add or overwrite, e.g. {"TAG": "v2"} env_remove: Names of Env variables to delete prune: Remove services no longer in the compose file (Swarm only). Defaults to the stack's current setting. pull_image: Force re-pulling images before redeploying (Portainer's "Re-pull image and redeploy"; default false) detach_from_git: Required to update a git-backed stack — Portainer converts it to a plain file-based stack and drops the git link and auto-update. Refused otherwise. endpoint_id: Endpoint ID (derived from the stack itself if omitted)

Inputs: stack_id (required), env, prune, env_remove, +4 more. Returns: result

portainer_stack_waitA

Wait for a stack's rollout to converge after stack_update.

Polls portainer_stack_status until every service is healthy, a service's update paused on failure, or the timeout elapses. Returns the final status with converged, reason and timed_out.

Args: stack_name: Stack name (Swarm namespace / Compose project) timeout_seconds: How long to wait (default 120, clamped to 5..PORTAINER_LONG_TIMEOUT) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: stack_name (required), endpoint_id, timeout_seconds. Returns: result

portainer_statusA

Check Portainer connection and authentication status.

Also reports how many endpoints Portainer knows and whether the default endpoint is a Swarm cluster — the first thing an agent needs to decide between the service-level and container-level tools.

Inputs: no named parameters. Returns: result

portainer_user_inspectA

Get details of a specific Portainer user.

Args: user_id: The ID of the user to inspect

Inputs: user_id (required). Returns: result

portainer_users_listB

List all Portainer users.

Inputs: no named parameters. Returns: result

portainer_volume_createA

Create a Docker volume.

Args: name: Volume name driver: Volume driver (default 'local') labels: Optional labels as key-value pairs endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: name (required), driver, labels, endpoint_id. Returns: result

portainer_volume_inspectA

Get detailed information about a Docker volume.

Args: volume_name: Volume name endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: volume_name (required), endpoint_id. Returns: result

portainer_volume_removeA

Remove a Docker volume.

Args: volume_name: Volume name force: Force removal even if in use (default false) endpoint_id: Target endpoint ID (uses default if omitted)

Inputs: volume_name (required), force, endpoint_id. Returns: result

portainer_volumes_listA

List Docker volumes on an endpoint.

Args: endpoint_id: Target endpoint ID (uses default if omitted) name_filter: Only return volumes whose name contains this substring (server-side Docker filter)

Inputs: endpoint_id, name_filter. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 53 tools

    Disambiguation4/5

    Tools are grouped by resource (stack, container, service, network, volume, image) and each pairs a resource with a distinct action, so most choices are clear. A few adjacent tools could still be confused (portainer_status vs portainer_docker_info, stack_status vs services_list, and the three log-scanning variants), but their descriptions draw workable boundaries.

    Naming Consistency4/5

    Nearly all tools follow the portainer_<resource>_<action> snake_case pattern, with plural list verbs (containers_list) and singular inspect verbs (container_inspect). Exceptions like portainer_status, portainer_docker_disk_usage, portainer_service_tasks, and portainer_container_logs break the action suffix pattern but remain readable.

    Tool Count2/5

    With 53 tools this is a very large surface for an agent to reason over, even though the Docker/Portainer domain genuinely has many resource types. It exceeds the comfortable 3–15 range by a wide margin and will make tool selection and prompt context heavier.

    Completeness4/5

    Docker resource coverage is strong: stacks, containers, services, images, volumes, and networks all have list/inspect plus lifecycle actions, and service/stack wait tools close rollout dead ends. Gaps are mostly in Portainer-admin resources (users, endpoints, registries, secrets/configs are read-only) and there is no container create, but agents can work around most of these via stacks.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Docker containers, deploy stacks, and monitor services across multiple Docker hosts from one centralized location. Supports container lifecycle management, Docker Compose operations, and infrastructure orchestration through natural language commands.
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Docker containers, stacks, images, volumes, and networks through Portainer's API. Supports listing resources, viewing logs, and performing container operations with configurable write permissions.
      1
      MIT