portainer-mcp
The portainer-mcp server equips AI assistants with 41 tools to manage Portainer container environments through natural language, supporting Docker Swarm and standalone setups.
Authentication & Status: Check Portainer connection and authentication status.
Endpoints (Environments): List all Portainer environments and inspect details of a specific one (sensitive fields filtered).
Stack Management: List, inspect (including Docker Compose content), deploy (auto-detects Swarm vs standalone), update, delete, start, and stop stacks.
Container Management: List (optionally including stopped), inspect, start, stop, restart, and remove containers; retrieve logs with tail limits; search logs via server-side regex (grep with context lines); get point-in-time CPU, memory, network, and block I/O stats; execute shell commands inside running containers (audit-logged); and scan all containers in a stack for error patterns (HTTP 4xx/5xx, exceptions, OOM, etc.).
Laravel-Specific Tools: Read Laravel application error logs from stack containers and execute PHP code via php artisan tinker inside a stack's backend container.
Image Management: List, inspect (by ID, name:tag, or digest), pull (with optional private registry authentication), and remove images.
Volume Management: List, inspect, create (with custom driver and labels), and remove volumes.
Network Management: List, inspect, create (bridge or overlay for Swarm), remove, connect containers to, and disconnect containers from networks.
System Information: Get Docker system info (OS, CPU, memory, container counts, swarm state) and disk usage by category (containers, images, volumes, build cache).
User Management: List and inspect Portainer users, with sensitive fields (e.g., password hashes) filtered out.
Integrates with Docker through Portainer, enabling container lifecycle management, image pulling, volume and network operations, and swarm awareness for cluster management.
Offers Laravel-specific debugging tools such as reading Laravel error logs and executing artisan tinker commands within containers of a stack.
Provides tools to manage Portainer environments, including deploying and updating stacks, managing containers, images, volumes, and networks, executing commands, analyzing logs, and inspecting endpoints.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@portainer-mcp deploy the nginx stack from the docker-compose.yml"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Portainer MCP Server
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 forreveal_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/updateequivalents 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-mcpOr 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.serverCursor
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 |
| Yes | — | Portainer base URL, e.g. |
| One of | — | Portainer access token, sent as |
| One of | — | Portainer username (with |
| One of | — | Portainer password |
| No |
| Default endpoint ID for container/image/stack operations |
| No |
| Set to |
| No |
| Timeout (seconds) for ordinary API calls |
| No |
| Timeout (seconds) for long-running operations: image pull, container exec, large log scans |
| No |
| Max concurrent HTTP connections to Portainer |
| No |
| Max idle keep-alive connections |
| No |
| Proactive JWT refresh interval (seconds). Set below Portainer's session timeout (default 8h) to avoid per-call 401 re-auth round-trips. Unused with |
| No |
| Register the opinionated Laravel helpers ( |
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 |
| Check connection and authentication status. Returns version, instance ID, auth mode, the number of endpoints and, for the default endpoint, its name/status and |
Endpoints (Environments)
Tool | Description |
| List all environments. Returns id, name, type, url, status. |
| Get endpoint details (sensitive fields like TLS certs are filtered; the bulky raw |
Stacks
Tool | Description |
| List all stacks with id, name, type ( |
| Get stack details, its Env variables and the compose file. Credential-looking values ( |
| Deploy a new stack with optional Env variables. Auto-detects Swarm vs standalone. |
| 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 |
| 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). |
| Poll |
| Delete a stack (endpoint derived from the stack; a different |
| Start a stopped stack (endpoint derived from the stack). |
| Stop a running stack (endpoint derived from the stack). |
Swarm
Tool | Description |
|
|
| Full service definition (spec, previous spec, update status). Credential-looking |
|
|
| Aggregated logs of all the service's tasks across nodes. |
|
|
|
|
| Poll until the service is healthy and its update finished, the update paused on failure, or the timeout elapses. Returns the service summary with |
| Swarm secrets: names and metadata only, never values. |
| Swarm configs: names and metadata only, never content. |
| Swarm nodes: hostname, role, availability, state, leader, engine version, CPUs/memory, labels. |
Containers
Tool | Description |
| List containers with their |
| Get detailed container info. |
| Start a stopped container. |
| Stop a running container. |
| Restart a container. |
| Remove a container. |
| Get container logs as a JSON envelope ( |
| Server-side regex over logs. Returns only matching lines (with optional context) — saves bandwidth on noisy logs. |
| Point-in-time CPU%, memory, network and block I/O stats (not a stream). |
| Run a shell command inside a running container and return its stdout/stderr + exit code. Audit-logged. |
| 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 |
| Read |
| Execute PHP via |
Images
Tool | Description |
| List images with tags and sizes. |
| Get detailed image info. Accepts |
| Pull an image. |
| Remove an image. |
| Registries configured in Portainer (id, name, URL, type, authentication flag) — the |
Volumes
Tool | Description |
| List Docker volumes. |
| Get detailed volume info. |
| Create a volume. |
| Remove a volume. |
Networks
Tool | Description |
| List Docker networks with driver, scope and attached container count. |
| Get detailed network info. |
| Create a network. |
| Remove a network. |
| Attach a container to a network. |
| Detach a container from a network. |
System
Tool | Description |
| OS, CPU, memory, container/image counts, |
| Per-category disk usage (containers, images, volumes, build cache) with reclaimable size. |
| Reclaim disk: |
Users
Tool | Description |
| List all Portainer users with id, username, role. |
| 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 asX-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-Tokenare sent only on mutating methods; CSRF token is harvested fromX-CSRF-Tokenresponse 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_inspectstrips TLS certificates, Azure credentials and security settings;user_inspectwhitelists safe fields and hides password/TFA material;registries_listnever returns registry credentials.Credential masking —
stack_inspectandservice_inspectmask Env values whose name looks like a credential (and anyuser:pass@inside URLs) as[REDACTED];reveal_env=trueshows them. A compose file or Env value containing[REDACTED]is refused bystack_update, so a masked value can never overwrite a real one.stack_updatepreserves 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-Authfor private-registry image pulls is passed in via parameter, never persisted.Container removal —
forcedefaults tofalseto 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.serverLint, 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/
pytestRequirements
Python 3.10+
A running Portainer instance (CE or Business Edition)
Portainer API access (default port 9443)
License
Available Tools
53 toolsportainer_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
Scored across 53 tools
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.
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.
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.
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
Related MCP Connectors
Inspect and control your Northflank projects, services, jobs, and builds from your AI assistant.
Manage your own cloud with AI: deploy apps, push and ship custom Docker images, manage resources via your AI agent.
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
Deploy and run your apps by asking your AI: services, Postgres, logs, traces, rollbacks, costs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.6MIT
- AlicenseAqualityDmaintenanceEnables AI models to manage Docker containers, images, networks, and volumes through the Portainer API, providing comprehensive container orchestration capabilities.21MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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.1MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Docker containers, images, networks, and services through the Portainer API.-