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:
   ```bash
   git clone https://github.com/yourusername/portainer-mcp.git
   cd portainer-mcp
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

3. Configure environment variables:
   ```bash
   cp .env.example .env
   # Edit .env with your Portainer URL and API key
   ```

4. Make the server executable:
   ```bash
   chmod +x portainer_stacks_server.py
   ```

## Configuration

Add to your Claude Desktop configuration:

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

```javascript
// 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

```javascript
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

```javascript
// 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

```javascript
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:
```bash
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