portainer-mcp/README_DOCKER.md

Portainer Docker MCP Server

This MCP server provides comprehensive Docker and Docker Swarm management functionality through Portainer Business Edition.

Features

Container Management

• List and Inspect Containers

  • View all containers with status, ports, and resource usage
  • Get detailed container information including networks, mounts, and environment
  • Support for both running and stopped containers

• Container Lifecycle

  • Create containers with custom configurations
  • Start, stop, and restart containers
  • Remove containers (with force option)
  • View container logs with tail and timestamp options

Image Management

• Docker Images
  • List all images with sizes and tags
  • Pull images from registries
  • Remove unused images
  • Support for multi-tag images

Volume Management

• Docker Volumes
  • List volumes with mount points
  • Create named volumes
  • Remove volumes
  • Support for different volume drivers

Network Management

• Docker Networks
  • List networks with details
  • Create custom networks (bridge, overlay, etc.)
  • Remove networks
  • Configure internal networks

Docker Swarm Features

• Service Management

  • List services with replica status
  • Create services with scaling options
  • Update service configurations
  • Remove services
  • View service logs

• Stack Deployment

  • Deploy stacks from Docker Compose files
  • List stacks across environments
  • Remove stacks with all resources
  • Support for environment variables in stacks

System Information

• Docker Info
  • System-wide Docker information
  • Resource usage statistics
  • Swarm cluster status
  • Version information

Installation

1. Ensure Python dependencies are installed:

cd /Users/adelorenzo/repos/portainer-mcp
.venv/bin/pip install mcp httpx

2. Configure in Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "portainer-docker": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/portainer_docker_server.py"],
      "env": {
        "PORTAINER_URL": "https://your-portainer-instance.com",
        "PORTAINER_API_KEY": "your-api-key",
        "MCP_MODE": "true"
      }
    }
  }
}

3. Restart Claude Desktop

Available Tools

Container Operations

• list_containers - List all containers in an environment
• inspect_container - Get detailed container information
• create_container - Create a new container
• start_container - Start a stopped container
• stop_container - Stop a running container
• restart_container - Restart a container
• remove_container - Remove a container
• get_container_logs - View container logs

Image Operations

• list_images - List Docker images
• pull_image - Pull an image from registry
• remove_image - Remove an image

Volume Operations

• list_volumes - List Docker volumes
• create_volume - Create a new volume
• remove_volume - Remove a volume

Network Operations

• list_networks - List Docker networks
• create_network - Create a new network
• remove_network - Remove a network

Swarm Service Operations

• list_services - List Swarm services
• create_service - Create a new service
• update_service - Update service configuration
• remove_service - Remove a service
• get_service_logs - View service logs

Stack Operations

• list_stacks - List deployed stacks
• deploy_stack - Deploy a new stack
• remove_stack - Remove a stack

System Operations

• get_docker_info - Get Docker system information
• get_docker_version - Get Docker version details

Usage Examples

Container Management

# List all containers in environment 3
Use "list_containers" with environment_id: 3, all: true

# Create and start an nginx container
Use "create_container" with:
- environment_id: 3
- image: "nginx:latest"
- name: "my-nginx"
- ports: {"80/tcp": [{"HostPort": "8080"}]}

# View container logs
Use "get_container_logs" with:
- environment_id: 3
- container_id: "my-nginx"
- tail: 50
- timestamps: true

Docker Swarm Services

# Create a replicated service
Use "create_service" with:
- environment_id: 4
- name: "web-service"
- image: "nginx:alpine"
- replicas: 3
- ports: [{"target": 80, "published": 8080, "protocol": "tcp"}]

# Scale a service
Use "update_service" with:
- environment_id: 4
- service_id: "web-service"
- replicas: 5

Stack Deployment

# Deploy a stack
Use "deploy_stack" with:
- environment_id: 4
- name: "my-app"
- compose_file: |
    version: '3.8'
    services:
      web:
        image: nginx:alpine
        ports:
          - "8080:80"
      redis:
        image: redis:alpine

Docker Volumes

# Create a volume
Use "create_volume" with:
- environment_id: 3
- name: "app-data"
- driver: "local"

# List volumes
Use "list_volumes" with environment_id: 3

Container Configuration

When creating containers, you can specify:

• Image: Docker image name with optional tag
• Name: Container name (optional)
• Command: Override default command
• Environment Variables: Array of KEY=VALUE strings
• Ports: Port bindings (host:container mapping)
• Volumes: Volume mounts
• Restart Policy: no, always, unless-stopped, on-failure

Swarm vs Standalone

This server automatically handles both:

• Docker Standalone: Container operations, local volumes, bridge networks
• Docker Swarm: Services, stacks, overlay networks, multi-node deployments

Some operations (like services) only work on Swarm environments.

Error Handling

The server provides clear error messages:

• Environment not found
• Container/service not found
• Swarm-only operations on standalone Docker
• Network connectivity issues
• Permission errors

Security Notes

• API key is required for all operations
• Container operations respect Portainer's RBAC
• Sensitive environment variables are filtered from logs
• Force options available for cleanup operations

Limitations

• Log output is limited to prevent overwhelming responses
• Large container lists are truncated (shows first 20)
• Stack deployment requires compose file as string
• Some Docker features may require direct API access