# portainer/portainer-mcp [Health: Active]

**Category:** ☁️ Cloud Platforms  
**Repository:** https://github.com/portainer/portainer-mcp  
**GitHub Stars:** 239  
**Views:** 9  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/portainer-portainer-mcp

## Description
/🏠 - A powerful MCP server that enables AI assistants to seamlessly interact with Portainer instances, providing natural language access to container management, deployment operations, and infrastructure monitoring capabilities.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "portainer-mcp": {
    "command": "uvx",
    "args": ["--from","mcp-portainer~=2.45.0","mcp-portainer"],
    "env": {
      "PORTAINER_URL": "",
      "PORTAINER_API_KEY": "",
      "PORTAINER_MCP_ALLOWED_HOSTS": "",
      "PORTAINER_MCP_AUTH_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `PORTAINER_URL`, `PORTAINER_API_KEY`, `PORTAINER_MCP_ALLOWED_HOSTS`, `PORTAINER_MCP_AUTH_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What portainer/portainer-mcp does

portainer/portainer-mcp turns Portainer's REST API into MCP tools for an AI client. The exposed operations cover environment discovery and inspection, GitOps workflow management, and troubleshooting for Docker and Kubernetes resources. It can also forward requests to the Docker and Kubernetes APIs associated with individual Portainer environments.

The implementation is generated from the Portainer OpenAPI specification using FastMCP. Its scope follows the permissions of the Portainer identity used for each request, making the Portainer API key an important part of the access model.

## How it works

For local use, the server runs as a stdio process and connects directly to a Portainer instance. The documented `uvx` command starts the Python package and passes the Portainer URL and API key as environment variables. An MCP bundle provides another local installation path for clients that support MCP bundles.

For shared access, run the published container inside private infrastructure and expose its MCP endpoint over HTTPS. The container can terminate TLS itself, sit behind a TLS-terminating reverse proxy, or use plaintext HTTP when explicitly enabled for a trusted private network. HTTP deployments use a shared front-gate token, while each caller also supplies a Portainer API key so requests use that caller's Portainer identity. An identity-aware proxy can take ownership of the authorization header instead.

Match the server's minor version to the Portainer instance's minor version. For example, a 2.45.x server is intended for a 2.45.x Portainer instance.

## Setup and configuration

Create an API key in Portainer under **My Account → Access tokens** before using the server. A local stdio setup needs `PORTAINER_URL` and `PORTAINER_API_KEY`. Self-signed Portainer certificates require `PORTAINER_TLS_VERIFY=0`.

Container-based HTTP deployments must define `PORTAINER_MCP_ALLOWED_HOSTS`; requests whose host is not allowed are rejected by the DNS-rebinding protection. They also require `PORTAINER_MCP_AUTH_TOKEN`, unless an identity-aware proxy is trusted with `PORTAINER_MCP_TRUST_PROXY_AUTH=1`. The MCP client sends the gate token in `Authorization` and the user's Portainer key in `X-Portainer-API-Key`.

When the container handles TLS, provide `PORTAINER_MCP_TLS_CERT` and `PORTAINER_MCP_TLS_KEY`. With a reverse proxy, enable `PORTAINER_MCP_TRUST_PROXY_TLS=1` and restrict trusted proxy addresses with `PORTAINER_MCP_FORWARDED_ALLOW_IPS`. Plain HTTP requires the explicit `PORTAINER_MCP_DANGEROUSLY_ALLOW_PLAINTEXT_HTTP=1` setting.

## Tools and capabilities

- List and inspect Portainer environments.
- Manage GitOps workflows through Portainer.
- Troubleshoot Docker resources.
- Troubleshoot Kubernetes resources.
- Proxy requests to an environment's Docker API.
- Proxy requests to an environment's Kubernetes API.

## Limitations and notes

Portainer no longer supports this project as its recommended LLM integration; Portainer Command is the supported alternative for Portainer Business Edition customers, including the free 3-node license. portainer/portainer-mcp is retained as-is without support, warranty, SLA, guaranteed issue response, planned feature development, or roadmap commitment.

Use it for evaluation, homelabs, and other non-production scenarios. The project is not recommended where uptime, security posture, or data integrity are important. Do not expose the container publicly; keep it in private infrastructure, including when placing it behind a TLS proxy. In HTTP mode, the shared gate secret and user Portainer keys travel over the connection, so the TLS and proxy posture must be configured deliberately.

_Full upstream README: https://allmcps.com/mcp/portainer-portainer-mcp/readme_