MCP Directory

How to add Portainer MCP to Windsurf

Official Portainer MCP server: manage Docker, Kubernetes, and GitOps environments via the Portainer REST API. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

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

Windsurf 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 Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Portainer MCP config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Portainer MCP's tools become available to Cascade.

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 Windsurf

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

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Portainer MCP config there under the "mcpServers" key and restart the client.

Is Portainer MCP safe to use with Windsurf?

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