Portainer MCP

by portainer

195 stars
409 downloads
Not rated
GitHub Website

About

Manage Portainer resources and execute Docker or Kubernetes commands through an AI assistant.

Details

Author
portainer
GitHub stars
195
Downloads
409
Categories
Cloud Service, Infrastructure, Other

Jump to

- Exposes Portainer REST API as MCP tools
- List, inspect, and manage environments
- Manage GitOps workflows
- Troubleshoot Docker and Kubernetes resources
- Proxy to underlying Docker and K8s APIs
- Multiple deployment modes: local, bundle, container
- Supports capability profiles to restrict or expand tools
- Environment variable redaction enabled by default
- Gate token authentication for team container deployment
- Version must match Portainer instance minor version

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Portainer MCP
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

Portainer MCP can be deployed locally via uvx (stdio), installed as a self-contained MCP bundle, or deployed as a container for team use. You need a Portainer URL and an API key (generated under My Account → Access tokens). For a local test, register with Claude Code using claude mcp add portainer -e PORTAINER_URL=... -e PORTAINER_API_KEY=... -- uvx --from "mcp-portainer~=2.43.0" mcp-portainer. The container deployment requires a shared gate token (PORTAINER_MCP_AUTH_TOKEN) and each user forwards their own Portainer API key.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "portainer mcp": {
            "portainer-mcp": {
                "command": "docker",
                "args": [
                    "run",
                    "-d",
                    "--name",
                    "portainer-mcp",
                    "-p",
                    "17717:17717",
                    "\\"
                ]
            }
        }
    }
}

McpServers

{
    "portainer-mcp": {
        "command": "docker",
        "args": [
            "run",
            "-d",
            "--name",
            "portainer-mcp",
            "-p",
            "17717:17717",
            "\\"
        ]
    }
}

Official MCP server for Portainer, generated from the Portainer OpenAPI spec viaFastMCP.

This MCP server exposes the Portainer REST API as MCP tools: list and inspect environments, manage GitOps workflows, troubleshoot Docker and Kubernetes resources. It also supports proxying requests to the underlying Docker and K8s APIs of each environment.

Match the MCP server's minor version to your Portainer instance's minor — e.g. MCP server 2.44.x with Portainer 2.44.x. SeeVersion compatibilityfor details.

The MCP server supports different deployment scenarios:

- execute it locally viauvx
- install it as a MCP bundle
- deploy it as a container

Use theuvxapproach or the MCP bundle to explore the MCP capabilities locally and deploy it inside your infrastructure as a container for a team based deployment setup.

[!NOTE] Before using the MCP, make sure to generate an API key in Portainer underMy Account → Access tokensfirst as both paths need it.

The recommended way to test the MCP server locally. Your client must supportMCP bundles:
- Fetch the self-contained.mcpbbundle for your platform from thelatest release
- Double-click to install
- Enter your Portainer URL and API key.

The other way to test the MCP server locally. Runs as a stdio process on your machine and connects directly to the Portainer instance.

[!NOTE]uvmust be installed and available onPATH. Seethe uv install docs.

SetPORTAINER_TLS_VERIFY=0if your Portainer instance uses self-signed TLS certificates.

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

For other clients, seedocs/distribution/.

The recommended way to have multiple users interacting with your Portainer instance via MCP. Deployed as acontainerinside your infrastructure, accessed by users from their workstations over HTTPS. A shared secret gates the MCP server and every client also forwards its own Portainer API key so that each user acts under their own Portainer identity.

[!IMPORTANT] Both the gate secret and each user Portainer API key are sent across the wire. The container deployment requires you to declare a transport posture: bring your own TLS certificates, attest a TLS-terminating reverse proxy setup or explicitly opt-in to plaintext.

Plaintext is a deliberate, dangerous choice — see the three options below.

It isNOTrecommended to expose this MCP server on the public internet, host it inside your private infrastructure even behind a TLS proxy.

See more info below about the different deployment scenarios. For any of these scenarios:

- SetPORTAINER_MCP_ALLOWED_HOSTSto the hostname or IP address that users will use to reach the MCP — otherwise the DNS-rebinding allowlist 421-rejects the request.
- PORTAINER_MCP_AUTH_TOKENisrequiredin HTTP mode. It's the shared front-gate secret you distribute to your users; their MCP client sends it via theAuthorizationheader. It only admits the request — what each user candois governed by their own Portainer API key. The one exception: behind an identity-aware proxy that owns theAuthorizationheader, usePORTAINER_MCP_TRUST_PROXY_AUTH=1instead (see Option D).

[!NOTE] The server will warn if using self-signed certificates. Using a private CA cert won't warn, but in both cases you will likely need to jump through some hoops to configure the MCP clients to accept it.

Deploy the container to use your own set of TLS certificates:

TOKEN=$(openssl rand -hex 32) docker run -d --name portainer-mcp -p 17717:17717 \ -v /etc/portainer-mcp/tls:/tls:ro \ -e PORTAINER_URL=https://portainer.example.com \ -e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \ -e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com:17717 \ -e PORTAINER_MCP_TLS_CERT=/tls/cert.pem \ -e PORTAINER_MCP_TLS_KEY=/tls/key.pem \ portainer/portainer-mcp:2.44

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

[!NOTE] Don't publish the container port when using a reverse proxy in front of the MCP container, only the proxy should be able to reach it.

Use your proxy exact IP if stable forPORTAINER_MCP_FORWARDED_ALLOW_IPS.

Make sure that your proxy forwards the originalHostand theX-Forwarded-Proto: httpsheaders.

BYO proxy and set up a TLS-terminated proxy in front of the container:

TOKEN=$(openssl rand -hex 32) docker run -d --name portainer-mcp \ -e PORTAINER_URL=https://portainer.example.com \ -e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \ -e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com \ -e PORTAINER_MCP_TRUST_PROXY_TLS=1 \ -e PORTAINER_MCP_FORWARDED_ALLOW_IPS=172.18.0.0/16 \ portainer/portainer-mcp:2.44

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

[!WARNING] It isNOTrecommended to use this outside of a trusted private network deployment.

Use thePORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1flag to start the server with HTTP only.

TOKEN=$(openssl rand -hex 32) docker run -d --name portainer-mcp -p 17717:17717 \ -e PORTAINER_URL=https://portainer.example.com \ -e PORTAINER_MCP_AUTH_TOKEN="$TOKEN" \ -e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com:17717 \ -e PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1 \ portainer/portainer-mcp:2.44

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

Option D - Identity-aware proxy (MCP OAuth)

If your users authenticate through an identity-aware proxy that speaks the MCP OAuth flow (such asPomerium in MCP server mode), the proxy mints its own access token andownstheAuthorizationheader. Declare the trust-proxy auth posture instead ofPORTAINER_MCP_AUTH_TOKEN:

[!NOTE] Same rules as Option B: don't publish the container port (only the proxy may reach it), and make sure the proxy forwards the originalHostandX-Forwarded-Proto: httpsheaders.

Each request still needs the caller's own Portainer API key inX-Portainer-API-Key— have the proxy inject it per-user, or have each client send it. The proxy handleswho gets in; the Portainer key governswhat they can do.

docker run -d --name portainer-mcp \ -e PORTAINER_URL=https://portainer.example.com \ -e PORTAINER_MCP_TRUST_PROXY_AUTH=1 \ -e PORTAINER_MCP_ALLOWED_HOSTS=mcp.example.com \ -e PORTAINER_MCP_TRUST_PROXY_TLS=1 \ -e PORTAINER_MCP_FORWARDED_ALLOW_IPS=172.18.0.0/16 \ portainer/portainer-mcp:2.44

No gate token is configured: the request is admitted by proxy attestation (it must arrive fromPORTAINER_MCP_FORWARDED_ALLOW_IPS— inherited as the trust boundary,*refuses to boot) and by the caller's validated Portainer key. If the MCP server terminates TLS itself instead of the proxy, setPORTAINER_MCP_TRUSTED_PROXY_AUTH_IPS=<proxy ip/cidr>in place of the twoTRUST_PROXY_TLS/FORWARDED_ALLOW_IPSlines. Seedocs/configuration.mdfor the full posture rules.

Restricting and expanding the MCP server capabilities

The MCP server comes with the following capabilities enabled by default:

- Basic Portainer operation support (settings, version, environments...)
- Docker operation support
- Kubernetes operation support
- Docker and Kubernetes proxy support
- Redacting environment variables values (enabled by default)

For restricting or expanding this set of capabilities, seedocs/profiles.md.

Match the MCP server's minor to your Portainer minor.The major+minor tracks the Portainer API version the embedded spec targets.

For more information about the versioning policy, seedocs/versioning.md.

The MCP server exposes different capabilities such as:

- Enable different set of tools based on specific profile configuration
- Widen the API coverage by specifying extra tags to cover
- Expose only read-only capabilities
- Disable proxy capabilities
- Tuning the transport capabilities and configuring the TLS posture
- Logging configuration

For more information about the MCP server configuration, refer todocs/configuration.md.

Navigate your Aiven projects and interact with the PostgreSQL®, Apache Kafka®, ClickHouse® and OpenSearch® services

Yunxiao MCP Server provides AI assistants with the ability to interact with the Yunxiao platform.

Get prescriptive CDK advice, explain CDK Nag rules, check suppressions, generate Bedrock Agent schemas, and discover AWS Solutions Constructs patterns.

This AWS Labs Model Context Protocol (MCP) server for CloudTrail enables your AI agents to query AWS account activity for security investigations, compliance auditing, and operational troubleshooting.

Core AWS MCP server providing prompt understanding and server management capabilities.

Analyze CDK projects to identify AWS services used and get pricing information from AWS pricing webpages and API.

Query and analyze your Axiom logs, traces, and all other event data in natural language

Manage and interact with Microsoft Azure services.

Bastion: External Attack Surface Monitoring

Ask your AI assistant about your attack surface: run scans, catch expiring certificates and domains, triage findings, and generate reports.

Agent-ready global image CDN that AI agents can install and operate through MCP.

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

{
    "mcpServers": {
        "portainer mcp": {
            "portainer-mcp": {
                "command": "docker",
                "args": [
                    "run",
                    "-d",
                    "--name",
                    "portainer-mcp",
                    "-p",
                    "17717:17717",
                    "\\"
                ]
            }
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other

Reactive Resume

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

39.5k
Other