# Portainer MCP Server
An MCP (Model Context Protocol) server that enables AI assistants like Claude to manage Docker containers through Portainer's API.
> **Fair Warning:** This project has been thoroughly *vibe coded*. What does that mean? It means I built this for my own personal use and experimentation, guided primarily by vibes and AI-assisted development. Use at your own risk. Feel free to submit issues, but be aware they will be *vibe fixed* as well. No guarantees, no SLAs, just vibes.
## What is this?
This MCP server acts as a bridge between AI models and your Portainer instance. Once connected, your AI assistant can:
- List and inspect your Docker environments, containers, stacks, images, volumes, and networks
- View container logs
- Perform actions like starting, stopping, and removing containers
- Deploy new Docker Compose stacks
- Manage Docker resources (images, volumes, networks)
All write operations are disabled by default and must be explicitly enabled.
## Quick Start
### Docker (Recommended)
```bash
# Pull and run
docker run --rm \
-e PORTAINER_URL=https://portainer.example.com \
-e PORTAINER_API_KEY=ptr_your_key_here \
ghcr.io/caffeineflo/portainer-mcp:latest
```
### Node.js
```bash
# Install dependencies
pnpm install
# Build
pnpm build
# Run
PORTAINER_URL=https://portainer.example.com \
PORTAINER_API_KEY=ptr_your_key_here \
node dist/index.js
```
## Configuration
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PORTAINER_URL` | Yes | - | Your Portainer instance URL |
| `PORTAINER_API_KEY` | Yes | - | Portainer API access token |
| `PORTAINER_WRITE_ENABLED` | No | `false` | Set to `true` to enable write operations |
### Getting a Portainer API Key
1. Log into Portainer
2. Go to **My Account** → **Access Tokens**
3. Click **Add access token**
4. Give it a descriptive name and copy the generated token
## Claude Desktop Integration
Add to your Claude Desktop config:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
### Using Docker
```json
{
"mcpServers": {
"portainer": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "PORTAINER_URL=https://portainer.example.com",
"-e", "PORTAINER_API_KEY=ptr_your_api_key_here",
"-e", "PORTAINER_WRITE_ENABLED=true",
"ghcr.io/caffeineflo/portainer-mcp:latest"
]
}
}
}
```
### Using Node.js
```json
{
"mcpServers": {
"portainer": {
"command": "node",
"args": ["/path/to/portainer-mcp/dist/index.js"],
"env": {
"PORTAINER_URL": "https://portainer.example.com",
"PORTAINER_API_KEY": "ptr_your_api_key_here",
"PORTAINER_WRITE_ENABLED": "true"
}
}
}
}
```
## Available Tools
### Read-Only (Always Available)
| Tool | Description |
|------|-------------|
| `list_environments` | List all Portainer environments (Docker endpoints) |
| `list_containers` | List containers in an environment (optionally include stopped) |
| `inspect_container` | Get detailed information about a container |
| `container_logs` | Get container logs (default 100 lines, max 10,000) |
| `list_stacks` | List all stacks (optionally filter by environment) |
| `inspect_stack` | Get stack details including the compose file content |
| `list_images` | List Docker images in an environment |
| `list_volumes` | List Docker volumes in an environment |
| `list_networks` | List Docker networks in an environment |
### Write Operations (Require `PORTAINER_WRITE_ENABLED=true`)
| Tool | Description |
|------|-------------|
| `container_action` | Start, stop, restart, kill, or remove a container |
| `stack_action` | Start, stop, or remove a stack |
| `create_stack` | Create a new Docker Compose stack |
| `manage_image` | Pull or remove a Docker image |
| `manage_volume` | Create or remove a Docker volume |
| `manage_network` | Create or remove a Docker network (with optional custom subnet) |
## Example Workflows
### Check what's running
```
You: What containers are running in my environment?
Claude: Let me check...
→ list_environments
→ list_containers(environment_id=1)
You have 5 containers running:
- nginx (Up 2 days)
- postgres (Up 2 days)
- redis (Up 5 hours)
...
```
### View logs for a problematic container
```
You: Show me the last 50 lines of logs from the api container
Claude:
→ container_logs(environment_id=1, container_id="api", tail=50)
```
### Deploy a new stack
```
You: Deploy an nginx container as a stack called "webserver"
Claude:
→ create_stack(
environment_id=1,
name="webserver",
compose_content="services:\n web:\n image: nginx:latest\n ports:\n - '8080:80'"
)
```
## Development
```bash
# Install dependencies
pnpm install
# Build TypeScript
pnpm build
# Watch mode (rebuild on changes)
pnpm dev
# Run tests
pnpm test
# Bundle for distribution
pnpm bundle
# Build Docker image
docker build -t portainer-mcp .
```
## Project Structure
```
src/
├── index.ts # MCP server entry point
├── client.ts # Portainer API client
├── types.ts # TypeScript type definitions
├── schemas.ts # Zod validation schemas
└── tools/
├── index.ts # Tool registry and dispatcher
├── definitions.ts # MCP tool JSON Schema definitions
├── utils.ts # Response formatting utilities
├── environments.ts
├── containers.ts
├── stacks.ts
├── images.ts
├── volumes.ts
└── networks.ts
```
## Tech Stack
- **TypeScript** - Type safety throughout
- **@modelcontextprotocol/sdk** - MCP protocol implementation
- **Zod** - Runtime validation of tool arguments
- **Node.js 18+** - Runtime requirement
- **Docker** - Optimized multi-stage build (~148MB image)
## License
MIT
