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)

# 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

# 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

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

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

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

Write Operations (Require PORTAINER_WRITE_ENABLED=true)

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

# 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