# Portainer MCP

> Portainer MCP connects your AI agent to your entire container infrastructure, letting you manage Docker and Kubernetes environments through natural conversation. You can list containers across multiple endpoints, spin up new services from images, start dormant apps, and connect to remote clusters—all without leaving your chat interface.

## Overview
- **Category:** ship-it
- **Price:** Free
- **Tags:** docker, kubernetes, container-management, orchestration, infrastructure-as-code

## Description

Managing complex container setups usually means jumping between a dashboard, writing `docker-compose` files, or remembering specific CLI commands for different environments. This MCP changes that. It lets you talk to your infrastructure instead of clicking through menus. You can connect your AI agent to any environment—local Docker hosts or remote Kubernetes clusters—and treat them all as one system. Need to check the status of a service on an endpoint you haven't touched in weeks? Just ask. Want to deploy a new testing stack using a specific image? Tell your agent and watch it handle the creation process. Because Vinkius manages this catalog, you connect once from any compatible client and get immediate access to controlling all your core container operations. It’s about giving your AI agent complete operational control over your entire service lifecycle.

## Tools

### add_endpoint
Connects the MCP to a new environment, like a remote Docker host or Kubernetes cluster.

### authenticate
Generates a temporary security token needed for all subsequent operations on the platform.

### create_docker_container
Builds and creates a new container instance using a specified image name.

### init_admin
Sets up the initial administrative password for a brand-new Portainer installation.

### list_docker_containers
Retrieves and lists all existing containers, showing their current running or stopped status in an environment.

### start_docker_container
Restarts a container that is currently stopped or offline within the specified endpoint.

## Prompt Examples

**Prompt:** 
```
List all containers in Portainer endpoint 1.
```

**Response:** 
```
I've retrieved the container list for endpoint 1. You have 4 containers: 'nginx-proxy' (running), 'db-postgres' (running), 'redis-cache' (stopped), and 'app-worker' (running).
```

**Prompt:** 
```
Create a new container named 'web-server' using the 'nginx:latest' image in endpoint 2.
```

**Response:** 
```
The container 'web-server' has been successfully created in endpoint 2 using the nginx:latest image. Would you like me to start it now?
```

**Prompt:** 
```
Start the container 'redis-cache' in endpoint 1.
```

**Response:** 
```
Starting 'redis-cache' in endpoint 1... The container has been started successfully.
```

## Capabilities

### Check Container Status
List every Docker container running or stopped within a specified environment.

### Initialize Environments
Connect your AI agent to new or existing remote and local Docker/Kubernetes clusters (endpoints).

### Deploy New Containers
Create a brand-new container instance using a specific image name.

### Restart Services
Bring a stopped or dormant container back online with one command.

### Secure Access Credentials
Authenticate the MCP connection to generate temporary security tokens for authorized access.

## Use Cases

### Investigating Production Failures
An engineer notices latency spikes. They prompt their agent: 'List all containers in the production endpoint and tell me which ones are stopped.' The agent uses `list_docker_containers` to immediately pinpoint a misconfigured service that needs restarting.

### Spinning Up Local Testing Environments
A developer needs a fresh copy of their API backend for testing. They ask the agent to deploy it using `create_docker_container`, specifying the required image and port settings, all from within their IDE chat window.

### Onboarding New Infrastructure
The SysAdmin gets a new cluster endpoint URL. Instead of following a manual setup guide, they use `add_endpoint` through the agent, linking the whole remote system into their existing operational flow.

### Recovering a Forgotten Service Instance
A critical caching service was accidentally stopped during maintenance. The administrator simply asks the agent to 'start the redis container in staging,' which executes `start_docker_container` instantly, restoring service.

## Benefits

- You manage multiple remote clusters from one spot. The `add_endpoint` tool lets you connect to a staging cluster in AWS, and then immediately check its status alongside your local development container list.
- Eliminate manual setup headaches. Use the `init_admin` tool right away on fresh installs so your agent can grab secure credentials and start working instantly.
- Debugging is faster than ever. Instead of logging into a dashboard just to see what's wrong, ask your agent to `list_docker_containers` and get the status in three seconds.
- Deployment becomes conversational. You tell your agent to create a service using `create_docker_container`, specifying the image and configuration parameters directly in the chat prompt.
- Keep services online with zero effort. If an application container stops unexpectedly, you just ask your agent to `start_docker_container` instead of writing a restart command.

## How It Works

The bottom line is that you control complex container operations conversationally instead of through a dashboard or terminal.

1. First, subscribe to this MCP and provide your Portainer URL along with the necessary API key.
2. Next, you instruct your AI agent on what needs doing—for example, 'list all containers in my staging environment.'
3. The system executes the required action against your infrastructure and reports the status directly back to your chat.

## Frequently Asked Questions

**How do I list containers using the Portainer MCP?**
You use the `list_docker_containers` tool. Just ask your agent to check a specific environment, and it will return a structured list showing all running and stopped services.

**Can I connect multiple remote clusters with Portainer MCP?**
Yes. You use the `add_endpoint` tool to link various local or cloud-based Docker/Kubernetes environments, allowing your agent to treat them all as one resource pool.

**What if a container is stopped? How do I restart it?**
Use the `start_docker_container` tool. You just need to give the agent the name of the service and the endpoint, and it handles bringing the instance back online.

**Do I have to set up Portainer manually before using the MCP?**
Yes. For initial setup on a new system, you must first run `init_admin` to create the administrative credentials needed for the agent to gain access.

**Can I deploy a brand-new container with Portainer MCP?**
Absolutely. Use the `create_docker_container` tool by telling your agent the exact image and name you want, and it handles deploying the service for you.