Portainer MCP

Reviewed 2026-10-13devopsMCP Server# portainer # docker # kubernetes # mcp # devops

Portainer's MCP server (now deprecated upstream): lets AI agents inspect environments and manage Docker, Kubernetes and GitOps stacks through the Portainer API.

Security Reviewed

Acts on your Portainer with your API key and can change real infrastructure; read-only mode and secret redaction are available, and the project is deprecated upstream since 2026-10-08.

Install Portainer MCP in Google Antigravity

Antigravity reads MCP servers from ~/.gemini/config/mcp_config.json (all projects) or .agents/mcp_config.json (one project) (official docs).

EasiestOption 1: paste this to your Antigravity agent

Install the "Portainer MCP" MCP server for Google Antigravity.
Follow the steps at https://www.antigravityskills.org/install/portainer.md (source: https://github.com/portainer/portainer-mcp).
Before running anything, show me what you will download and whether it includes scripts, and wait for my OK.
Ask me for any keys or paths it needs. When done, check that it is listed under Installed MCP Servers.

The agent reads the install file, shows you what it will download and waits for your OK.

Option 2: install it yourself

1. Create a Portainer API key
In Portainer: My Account -> Access tokens. For look-only use, plan to set PORTAINER_READ_ONLY=1.
2. Open the Antigravity MCP config
Global: ~/.gemini/config/mcp_config.json. This project only: .agents/mcp_config.json.

3. Add the server under "mcpServers"

{
  "mcpServers": {
    "portainer": {
      "command": "uvx",
      "args": ["--from", "mcp-portainer~=2.45.0", "mcp-portainer"],
      "env": {
        "PORTAINER_URL": "https://portainer.example.com",
        "PORTAINER_API_KEY": "ptr_xxxxxxxxxxxxxxxx",
        "PORTAINER_READ_ONLY": "1"
      }
    }
  }
}

Same stdio command the README documents for Claude Desktop, plus read-only mode (remove that line to allow changes). Change 2.45.0 to your Portainer minor version. Needs uv on PATH.

4. Optional: add the hygiene skill
```
git clone --depth 1 https://github.com/portainer/portainer-mcp /tmp/portainer-mcp && mkdir -p .agents/skills && cp -r /tmp/portainer-mcp/skills/portainer-mcp-hygiene .agents/skills/
```
The server already serves this guide through get_guidance; copying the skill into .agents/skills/ (or ~/.gemini/config/skills/) just makes it visible in the skills list.
5. Check that it loaded
Open Settings -> Customizations -> Installed MCP Servers; portainer should be listed and switched on.

The README does not mention Antigravity; these steps put its documented uvx command into Antigravity's mcp_config.json. MCP servers do not go in .agents/skills/.

Using Claude Code, Cursor or Codex? See other assistants below.

What is Portainer MCP?

Portainer MCP is the MCP server from Portainer.io that turns the Portainer REST API into tools an AI agent can call, for people who run Docker or Kubernetes through Portainer and want to ask an agent what is failing, read logs or redeploy a stack. Important: since commit aae7d64 (2026-10-08) the README says it is no longer the supported way to use an LLM with Portainer, points to Portainer Command (Business Edition) instead, and calls it intended for evaluation and homelabs, not production. What we counted at that commit: the server is 15 Python files (about 2,700 lines) plus a bundled, patched Portainer OpenAPI spec with 465 operations; the default profiles (BASE, DOCKER, KUBERNETES, GITOPS) cover 233 of them, 116 of which are GET/HEAD, and PORTAINER_PROFILES=ALL exposes every operation. It has 5 runtime dependencies (fastmcp, httpx, jmespath, pyyaml, cryptography). It also ships an agent skill, skills/portainer-mcp-hygiene/SKILL.md (390 lines), that is copied into the wheel and served as the get_guidance tool.

How to use Portainer MCP?

Create an API key in Portainer (My Account -> Access tokens), then run the server locally with uvx, install the .mcpb bundle, or deploy the container for a team. Match the server's minor version to your Portainer version (2.45.x with 2.45.x). For a look-only setup set PORTAINER_READ_ONLY=1. On the first tool call of a conversation the server returns its operating guide instead of running the call (the guidance gate in guidance.py) and the agent retries; this repeats only after 30 minutes of idle time by default.

Key features of Portainer MCP

✓Portainer REST API as MCP tools, filtered by profiles: BASE, DOCKER, KUBERNETES, GITOPS, EDGE, ADMIN or ALL
✓docker_proxy and kubernetes_proxy tools per environment (GET only when PORTAINER_READ_ONLY=1)
✓Server-side JMESPath select parameter on every tool; responses capped at about 50,000 characters (hygiene SKILL.md)
✓Environment variable values redacted to [REDACTED] before select runs, so a projection cannot bypass it
✓Guidance gate: the first call per caller delivers the hygiene guide, then the agent retries (TTL 1800 s by default)
✓Runs via uvx (stdio), a one-click .mcpb bundle, or a container with HTTPS, a shared gate token and per-user Portainer keys

When to use Portainer MCP

1Asking an agent which containers or pods are failing in an environment
2Reading container or pod logs through the proxy tools
3Deploying, scaling or restarting Portainer-managed stacks
4A read-only audit persona for inventory checks

Installation & Setup Guide

MCP Server Integration

Follow these steps (taken from the project's own docs) to configure Portainer MCP in your development environment.

Step 1: Claude Code (stdio via uvx)claude

claude mcp add portainer -e PORTAINER_URL=https://portainer.example.com -e PORTAINER_API_KEY=ptr_xxxxxxxxxxxxxxxx -- uvx --from "mcp-portainer~=2.45.0" mcp-portainer

Source: README, "Single user (stdio via uvx)". Replace the URL and key with your own. Set PORTAINER_TLS_VERIFY=0 only for a self-signed certificate.

Step 2: Claude Desktop (manual JSON)claude

{
  "mcpServers": {
    "portainer": {
      "command": "uvx",
      "args": ["--from", "mcp-portainer~=2.45.0", "mcp-portainer"],
      "env": {
        "PORTAINER_URL": "https://portainer.example.com",
        "PORTAINER_API_KEY": "ptr_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Source: docs/distribution/claude-desktop.md. Add to claude_desktop_config.json and restart Claude Desktop, or download the .mcpb bundle from the latest release and double-click it.

Step 3: Team deployment (container)claude

claude mcp add portainer --transport http https://mcp.example.com:17717/mcp --header "Authorization: Bearer <gate-token>" --header "X-Portainer-API-Key: <ptr_user_key>"

Source: README, "Team deployment", Option A. Run the portainer/portainer-mcp container with PORTAINER_MCP_AUTH_TOKEN, PORTAINER_MCP_ALLOWED_HOSTS and TLS certificates first.

Step 4: Cursor and Codex: not documentedcursor / codex

The README sends other clients to docs/distribution/, which only has a Claude Desktop guide. Any MCP client that launches stdio servers can run the same uvx command, but the project gives no Cursor or Codex instructions.

Usage Example & Verification

Prompt / Request Example

1) README example (hygiene SKILL.md): EndpointList(select="[].{id:Id,name:Name,type:Type,status:Status}")
-> What happens: the agent resolves environment IDs first and gets back only four fields per environment instead of full snapshots; a wrong ID later fails with HTTP 404 instead of empty data.

2) Our example: "Which containers in my production environment have exited in the last day? Read only, change nothing."
-> What happens: the agent calls EndpointList, then docker_proxy with a GET on the containers endpoint and a select projection. With PORTAINER_READ_ONLY=1 the proxy refuses any non-GET call.

3) Our example: "Restart the web stack and confirm it is running."
-> What happens: only works without read-only mode. The hygiene skill warns that mutation calls return empty success payloads, so the agent must check the stack status with a separate read afterwards.

Installation Confirmation Method

In Antigravity open Settings -> Customizations -> Installed MCP Servers and check that portainer is enabled; then ask "list my Portainer environments". The first call returns the operating guide, the retry returns the list.

Security Review

Static review

Reviewed Date

2026-10-13

Audited Ref / Commit

aae7d64cf65943d8d48ad89f8b3cc948890905b7

Reviewer

antigravityskills.org (static code review)

Acts on your Portainer with your API key and can change real infrastructure; read-only mode and secret redaction are available, and the project is deprecated upstream since 2026-10-08.

Full review: scope, findings, risks

Audit Scope:README.md at HEAD aae7d64 (2026-10-08; the only change since the previously reviewed commit 468a41e is the README deprecation notice), docs/configuration.md, docs/profiles.md, docs/distribution/claude-desktop.md, pyproject.toml, skills/portainer-mcp-hygiene/SKILL.md, src/portainer_mcp/ (profiles.py, guidance.py, redaction.py and proxy.py read; grep over all modules for network, subprocess and environment variables; operations counted in data/portainer-patched.yaml), LICENSE. Static review only; nothing was executed.

Key Findings:Python server built with FastMCP from a patched Portainer OpenAPI spec. All HTTP requests go through one httpx client whose base URL is your PORTAINER_URL; the proxy tools forward to the Docker and Kubernetes APIs of your Portainer environments through that URL. No subprocess, eval or exec calls and no telemetry code in src/portainer_mcp. Needs PORTAINER_URL and PORTAINER_API_KEY (stdio); HTTP mode instead takes each user's key from the X-Portainer-API-Key header and needs PORTAINER_MCP_AUTH_TOKEN and PORTAINER_MCP_ALLOWED_HOSTS. Env-var values are redacted by default. PORTAINER_READ_ONLY=1 limits API tools to GET/HEAD and makes the proxy tools reject non-GET methods.

Identified Operational Risks & Permissions:Write tools can deploy, scale, restart and delete resources. PORTAINER_PROFILES=ALL also exposes user, team, role, LDAP, license and backup operations. PORTAINER_TLS_VERIFY=0 and PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 weaken transport security. Upstream support has ended (README, 2026-10-08), so security fixes are not promised.

We read the README and docs at commit aae7d64 and the server code (unchanged since 468a41e). server.py builds a single httpx.AsyncClient with base_url set to PORTAINER_URL; passthrough.py injects the caller's Portainer key into each request. proxy.py registers docker_proxy and kubernetes_proxy and, in read-only mode, rejects any method other than GET. profiles.py maps PORTAINER_PROFILES to OpenAPI tags (default BASE,DOCKER,KUBERNETES,GITOPS); ALL disables the filter. redaction.py replaces env and envvars values with [REDACTED] before the JMESPath select runs, unless PORTAINER_EXPOSE_ENV_VALUES is set. guidance.py answers the first tool call per caller with the hygiene guide and asks for a retry (TTL 1800 s, PORTAINER_MCP_DISABLE_GUIDANCE_GATE turns it off). No subprocess, eval or exec calls and no analytics code were found in src/portainer_mcp. The README now marks the project as unsupported and not for production.

Operational Notes & Known Limitations

Known Limitations

•Deprecated upstream since 2026-10-08: no support, no further feature development, not recommended for production (README at commit aae7d64)
•Needs a Portainer instance and a Portainer API key; local mode needs uv on PATH or a client that supports .mcpb bundles
•Server minor version must match your Portainer minor version (README table: 2.41.x to 2.45.x)
•The team container requires a TLS posture choice; the README warns that the gate secret and each user's key cross the wire
•Set-up docs cover Claude Code and Claude Desktop only; Antigravity, Cursor and Codex are not mentioned in the README or docs/

Frequently Asked Questions

Is the Portainer MCP safe?

It can change real infrastructure: deploy, scale, restart and delete stacks, and send requests to Docker and Kubernetes APIs. In our static review it only talks to the PORTAINER_URL you set, runs no subprocesses and has no telemetry. Use PORTAINER_READ_ONLY=1 for look-only use and keep env-value redaction on.

Is Portainer MCP deprecated?

Yes. Since 2026-10-08 the README says it is provided as-is without support and is not recommended for production; Portainer points to Portainer Command (Business Edition) instead. The code still works with Portainer 2.41.x to 2.45.x per the version table.

How do I install the Portainer MCP in Antigravity?

The repo does not document Antigravity. Put the README's uvx command (uvx --from mcp-portainer~=2.45.0 mcp-portainer with PORTAINER_URL and PORTAINER_API_KEY) into ~/.gemini/config/mcp_config.json, as shown above.

Can I limit what tools are exposed?

Yes. PORTAINER_PROFILES picks tool groups (default BASE,DOCKER,KUBERNETES,GITOPS; EDGE and ADMIN are opt-in; ALL removes the filter) and PORTAINER_READ_ONLY=1 keeps only GET/HEAD operations.

Supported Platforms

claude

View Source on GitHub

Keep exploring this topic

Browse the full Antigravity skills directory for more source-linked skills with install steps and static safety reviews.

More devops skills #portainer #docker #kubernetes #mcp Use cases

Related Skills

🚀

DigitalOcean MCP

@digitalocean-labs

DigitalOcean's open-source MCP server: manage Droplets, App Platform, databases, DNS, Kubernetes and more from an AI agent.

Static reviewacts in your accountsneeds API keynetwork access

digitaloceancloud

🛡️

Container Security (Snyk)

@snyk

Snyk's container-security skill: scan Docker images for OS and app vulnerabilities via the Snyk MCP server and fix Dockerfiles.

Static reviewinstructions onlyneeds API keynetwork accesswrites files

container-securitydocker

🚀

Cloudflare Wrangler

@cloudflare

Cloudflare's official wrangler skill: tells an AI agent how to deploy, configure and debug existing Wrangler-based Workers projects using current Cloudflare docs.

Static reviewacts in your accountsneeds API keyinstructions only

cloudflarewrangler