MCP Directory

How to add Portainer MCP to Cursor

Official Portainer MCP server: manage Docker, Kubernetes, and GitOps environments via the Portainer REST API. Paste the config into ~/.cursor/mcp.json and restart Cursor.

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

Cursor 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 Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
  2. 2Paste the Portainer MCP config below into the "mcpServers" object.
  3. 3Fill in placeholder secrets, then save.
  4. 4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
  5. 5Ask Cursor to use one of Portainer MCP's tools to confirm it's connected.

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 Cursor

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 + Cursor FAQ

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the Portainer MCP config there under the "mcpServers" key and restart the client.

Is Portainer MCP safe to use with Cursor?

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