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:
```bash
pip install mcp httpx aiohttp
# Or use the requirements file:
pip install -r requirements.txt
```

2. Configure in Claude Desktop (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "portainer-docker": {
      "command": "python",
      "args": ["/path/to/portainer-mcp/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