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 — 41 tools to manage Portainer container environments: deploy and update stacks, manage containers/images/volumes/networks, exec commands, analyze logs, debug Laravel apps, and inspect endpoints — all through natural language.

For LLM agents: This server connects via stdio transport. Every tool returns JSON. All mutating operations are audit-logged. Credentials are passed via environment variables, never hardcoded.

• Natural language DevOps — Ask your AI assistant to deploy a stack, check container logs, or pull an image.
• Swarm-aware — Automatically detects Docker Swarm clusters and uses the correct API.
• Safe by default — Input validation, path traversal protection, sensitive field filtering, and force-remove disabled by default.
• Works everywhere — Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Continue.dev.

pip install portainer-mcp

Or from source:

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

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

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_USERNAME": "admin",
 "PORTAINER_PASSWORD": "your-password",
 "PORTAINER_VERIFY_SSL": "false"
 }
 }
 }
}

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

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"
 }
 }
 }
}

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"
 }
 }
 }
}

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 }
 ]
}

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"

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.

All 41 tools are listed below with their parameters and descriptions. Every tool returns JSON.

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.

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) to get the current compose file, modify the image tag, then portainer_stack_update(stack_id, compose_content).

• 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.
• 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.

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 and type-check:

ruff check src/
mypy src/

• Python 3.10+
• A running Portainer instance (CE or Business Edition)
• Portainer API access (default port 9443)

MIT