portainer-mcp/README_STACKS.md

Portainer Stacks MCP Server

This MCP server provides comprehensive stack deployment and management capabilities through Portainer's API, supporting both Docker Compose and Kubernetes deployments.

Features

• Stack Management: List, create, update, start, stop, and delete stacks
• Docker Compose Support: Deploy stacks from file content or Git repositories
• Kubernetes Support: Deploy Kubernetes manifests as stacks
• Git Integration: Create and update stacks directly from Git repositories
• Environment Variables: Manage stack environment variables
• Stack Migration: Copy stacks between environments
• Multi-Environment: Work with stacks across different Portainer environments

Installation

1. Ensure you have the Portainer MCP servers repository:

   git clone https://github.com/yourusername/portainer-mcp.git
   cd portainer-mcp
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment variables:

   cp .env.example .env
   # Edit .env with your Portainer URL and API key
   

4. Make the server executable:

   chmod +x portainer_stacks_server.py
   

Configuration

Add to your Claude Desktop configuration:

{
  "portainer-stacks": {
    "command": "python",
    "args": ["/path/to/portainer-mcp/portainer_stacks_server.py"],
    "env": {
      "PORTAINER_URL": "https://your-portainer-instance.com",
      "PORTAINER_API_KEY": "your-api-key"
    }
  }
}

Available Tools

Stack Information

list_stacks

List all stacks across environments.

• Parameters:
  • environment_id (optional): Filter by environment ID

get_stack

Get detailed information about a specific stack.

• Parameters:
  • stack_id (required): Stack ID

get_stack_file

Get the stack file content (Docker Compose or Kubernetes manifest).

• Parameters:
  • stack_id (required): Stack ID

Stack Creation

create_compose_stack_from_file

Create a new Docker Compose stack from file content.

• Parameters:
  • environment_id (required): Target environment ID
  • name (required): Stack name
  • compose_file (required): Docker Compose file content (YAML)
  • env_vars (optional): Array of environment variables
    • name: Variable name
    • value: Variable value

create_compose_stack_from_git

Create a new Docker Compose stack from Git repository.

• Parameters:
  • environment_id (required): Target environment ID
  • name (required): Stack name
  • repository_url (required): Git repository URL
  • repository_ref (optional): Git reference (default: "main")
  • compose_path (optional): Path to compose file (default: "docker-compose.yml")
  • repository_auth (optional): Use authentication (default: false)
  • repository_username (optional): Git username
  • repository_password (optional): Git password/token
  • env_vars (optional): Array of environment variables

create_kubernetes_stack

Create a new Kubernetes stack from manifest.

• Parameters:
  • environment_id (required): Target environment ID
  • name (required): Stack name
  • namespace (optional): Kubernetes namespace (default: "default")
  • manifest (required): Kubernetes manifest content (YAML)

Stack Management

update_stack

Update an existing stack.

• Parameters:
  • stack_id (required): Stack ID
  • compose_file (optional): Updated compose file or manifest
  • env_vars (optional): Updated environment variables array
  • pull_image (optional): Pull latest images (default: true)

update_git_stack

Update a Git-based stack (pull latest changes).

• Parameters:
  • stack_id (required): Stack ID
  • pull_image (optional): Pull latest images (default: true)

start_stack

Start a stopped stack.

• Parameters:
  • stack_id (required): Stack ID

stop_stack

Stop a running stack.

• Parameters:
  • stack_id (required): Stack ID

delete_stack

Delete a stack and optionally its volumes.

• Parameters:
  • stack_id (required): Stack ID
  • delete_volumes (optional): Delete associated volumes (default: false)

Stack Operations

migrate_stack

Migrate a stack to another environment.

• Parameters:
  • stack_id (required): Stack ID
  • target_environment_id (required): Target environment ID
  • new_name (optional): New stack name

get_stack_logs

Get logs from all containers in a stack.

• Parameters:
  • stack_id (required): Stack ID
  • tail (optional): Number of lines from end (default: 100)
  • timestamps (optional): Show timestamps (default: true)

Usage Examples

Deploy a Docker Compose stack

// From file content
await use_mcp_tool("portainer-stacks", "create_compose_stack_from_file", {
  environment_id: "2",
  name: "wordpress-blog",
  compose_file: `version: '3.8'
services:
  wordpress:
    image: wordpress:latest
    ports:
      - "8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wordpress
      WORDPRESS_DB_PASSWORD: \${DB_PASSWORD}
    volumes:
      - wordpress_data:/var/www/html
  
  db:
    image: mysql:5.7
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wordpress
      MYSQL_PASSWORD: \${DB_PASSWORD}
      MYSQL_RANDOM_ROOT_PASSWORD: '1'
    volumes:
      - db_data:/var/lib/mysql

volumes:
  wordpress_data:
  db_data:`,
  env_vars: [
    { name: "DB_PASSWORD", value: "secure_password" }
  ]
});

// From Git repository
await use_mcp_tool("portainer-stacks", "create_compose_stack_from_git", {
  environment_id: "2",
  name: "microservices-app",
  repository_url: "https://github.com/myorg/microservices.git",
  repository_ref: "main",
  compose_path: "docker/docker-compose.prod.yml",
  env_vars: [
    { name: "ENVIRONMENT", value: "production" },
    { name: "API_KEY", value: "secret_key" }
  ]
});

Deploy a Kubernetes stack

await use_mcp_tool("portainer-stacks", "create_kubernetes_stack", {
  environment_id: "3",
  name: "nginx-deployment",
  namespace: "production",
  manifest: `apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.21
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
  type: LoadBalancer`
});

Manage stacks

// Update a stack
await use_mcp_tool("portainer-stacks", "update_stack", {
  stack_id: "5",
  compose_file: "updated compose content...",
  env_vars: [
    { name: "VERSION", value: "2.0" }
  ],
  pull_image: true
});

// Update Git-based stack
await use_mcp_tool("portainer-stacks", "update_git_stack", {
  stack_id: "7",
  pull_image: true
});

// Stop and start stacks
await use_mcp_tool("portainer-stacks", "stop_stack", {
  stack_id: "5"
});

await use_mcp_tool("portainer-stacks", "start_stack", {
  stack_id: "5"
});

// Delete stack with volumes
await use_mcp_tool("portainer-stacks", "delete_stack", {
  stack_id: "5",
  delete_volumes: true
});

Migrate stack between environments

await use_mcp_tool("portainer-stacks", "migrate_stack", {
  stack_id: "5",
  target_environment_id: "4",
  new_name: "wordpress-prod"
});

Stack Types

The server supports three types of stacks:

1. Swarm Stacks (Type 1): Docker Swarm mode stacks
2. Compose Stacks (Type 2): Standard Docker Compose deployments
3. Kubernetes Stacks (Type 3): Kubernetes manifest deployments

Error Handling

The server includes comprehensive error handling:

• Invalid stack configurations
• Git repository access errors
• Environment permission issues
• Network timeouts and retries
• Resource conflicts

All errors are returned with descriptive messages to help diagnose issues.

Security Notes

• Git credentials are transmitted securely but stored in Portainer
• Environment variables may contain sensitive data
• Stack files can include secrets - handle with care
• API tokens are never logged or exposed
• Use RBAC to control stack access

Best Practices

1. Environment Variables: Use environment variables for configuration instead of hardcoding values
2. Git Integration: Use Git repositories for version control and automated deployments
3. Naming Convention: Use consistent naming for stacks across environments
4. Volume Management: Be careful when deleting stacks with volumes
5. Migration Testing: Test stack migrations in non-production environments first

Troubleshooting

Common Issues

1. Stack creation fails: Check compose file syntax and image availability
2. Git authentication errors: Ensure credentials are correct and have repository access
3. Permission denied: Verify user has appropriate Portainer permissions
4. Stack update fails: Check for resource conflicts or invalid configurations

Debug Mode

Enable debug logging by setting in your environment:

DEBUG=true
LOG_LEVEL=DEBUG

Requirements

• Python 3.8+
• Portainer Business Edition 2.19+
• Valid Portainer API token with stack management permissions
• Docker or Kubernetes environments configured in Portainer