MCP Directory

How to add Portainer MCP to Claude Desktop

Official Portainer MCP server: manage Docker, Kubernetes, and GitOps environments via the Portainer REST API. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 182★ · stdio · apikey · official

Claude Desktop config for Portainer MCP

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

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

  1. 1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
  2. 2Paste the Portainer MCP config below under the top-level "mcpServers" key.
  3. 3Fill in any placeholder secrets (API keys, paths) in the snippet.
  4. 4Save the file, then fully quit and reopen Claude Desktop.
  5. 5Open a chat and confirm Portainer MCP's tools appear under the 🔌 tools menu.

Before you start

  • A Portainer instance (CE or EE) with a matching minor version (e.g. Portainer 2.42.x with server 2.42.x)
  • A Portainer API key generated under My Account -> Access tokens
  • uv installed and available on PATH for the uvx/stdio path (see https://docs.astral.sh/uv/getting-started/installation/), or Docker for the container deployment

What Portainer MCP can do in Claude Desktop

BASE profile tools

Server identity and configuration operations from tags auth, system, status, settings, motd. Effectively required as most workflows assume these are present.

DOCKER profile tools

Docker workload operations on Portainer-managed environments, from tags docker, endpoints, stacks.

KUBERNETES profile tools

Kubernetes workload operations including Helm releases, from tags kubernetes, helm, endpoints, stacks.

EDGE profile tools

Portainer Edge fleet management, from tags edge, edge_stacks, edge_jobs, edge_groups, edge_update_schedules, edge_configs.

ADMIN profile tools

Platform administration (identity, registries, backups, RBAC) from tags users, teams, team_memberships, roles, ldap, license, backup, registries, endpoint_groups, policies, resource_controls, tags.

docker_proxy

Proxies requests to the underlying Docker API of a managed environment. Registered by default; can be disabled with PORTAINER_NO_PROXY=1, and rejects non-GET requests in read-only mode.

kubernetes_proxy

Proxies requests to the underlying Kubernetes API of a managed environment. Registered by default; can be disabled with PORTAINER_NO_PROXY=1, and rejects non-GET requests in read-only mode.

Security

Generate an API key in Portainer under My Account -> Access tokens before use. Set PORTAINER_TLS_VERIFY=0 only for self-signed TLS certificates. For the container/HTTP deployment, both the gate secret (PORTAINER_MCP_AUTH_TOKEN) and each user's Portainer API key are sent across the wire, so TLS is required: bring your own certificates, attest a TLS-terminating reverse proxy, or explicitly opt into plaintext via PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 (dangerous). Set PORTAINER_MCP_ALLOWED_HOSTS to the reachable hostname/IP or the DNS-rebinding allowlist 421-rejects the request. It is NOT recommended to expose this MCP server on the public internet; host it inside private infrastructure even behind a TLS proxy. Environment variable values are redacted by default.

Portainer MCP + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the Portainer MCP config there under the "mcpServers" key and restart the client.

Is Portainer MCP safe to use with Claude Desktop?

Generate an API key in Portainer under My Account -> Access tokens before use. Set PORTAINER_TLS_VERIFY=0 only for self-signed TLS certificates. For the container/HTTP deployment, both the gate secret (PORTAINER_MCP_AUTH_TOKEN) and each user's Portainer API key are sent across the wire, so TLS is required: bring your own certificates, attest a TLS-terminating reverse proxy, or explicitly opt into plaintext via PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 (dangerous). Set PORTAINER_MCP_ALLOWED_HOSTS to the reachable hostname/IP or the DNS-rebinding allowlist 421-rejects the request. It is NOT recommended to expose this MCP server on the public internet; host it inside private infrastructure even behind a TLS proxy. Environment variable values are redacted by default.

Which server version should I use?

Match the MCP server's minor version to your Portainer instance's minor — e.g. server 2.42.x with Portainer 2.42.x. The major+minor tracks the Portainer API version the embedded spec targets.

How do I run it for a single user vs. a team?

For a single user, run it locally as a stdio process via uvx (or install the one-click .mcpb bundle in Claude Desktop). For a team, deploy the published container (portainer/portainer-mcp) over HTTPS: a shared gate secret (PORTAINER_MCP_AUTH_TOKEN) admits requests and each client forwards its own Portainer API key via the X-Portainer-API-Key header.

Why are so few tools exposed by default?

The Portainer spec has 400+ operations across 40+ tags, which is too noisy for MCP clients. The server uses a tag allowlist organized into profiles (default BASE,DOCKER,KUBERNETES). Use PORTAINER_PROFILES to enable more (e.g. EDGE, ADMIN), PORTAINER_TAGS_EXTRA to add orphan tags like observability or gitops, or PORTAINER_PROFILES=ALL to expose every operation.

View repo Full Portainer MCP page