portainer-mcp/README_KUBERNETES.md

# Portainer Kubernetes MCP Server

This MCP server provides comprehensive Kubernetes cluster management capabilities through Portainer's API.

## Features

- **Namespace Management**: List, create, and delete namespaces
- **Pod Operations**: List, view, delete pods, and access logs
- **Deployment Management**: Create, scale, update, restart, and delete deployments
- **Service Management**: List, create, and delete services
- **Ingress Configuration**: List and create ingress rules
- **ConfigMap & Secret Management**: Full CRUD operations with base64 encoding
- **Storage Management**: PersistentVolume and PersistentVolumeClaim operations
- **Node Information**: View cluster node details

## 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 mcp httpx aiohttp
   # Or use the requirements file:
   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_kubernetes_server.py
   ```

## Configuration

Add to your Claude Desktop configuration:

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

## Available Tools

### Namespace Management

#### list_namespaces
List all namespaces in the cluster.
- **Parameters**:
  - `environment_id` (required): Target environment ID

#### create_namespace
Create a new namespace.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `name` (required): Namespace name

#### delete_namespace
Delete a namespace.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `name` (required): Namespace name

### Pod Management

#### list_pods
List pods in a namespace.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (optional): Namespace (default: "default")
  - `label_selector` (optional): Label selector (e.g., "app=nginx")

#### get_pod
Get detailed information about a specific pod.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Pod name

#### delete_pod
Delete a pod.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Pod name
  - `grace_period` (optional): Grace period in seconds

#### get_pod_logs
Get logs from a pod.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Pod name
  - `container` (optional): Container name
  - `previous` (optional): Get previous container logs
  - `tail_lines` (optional): Number of lines from end

### Deployment Management

#### list_deployments
List deployments in a namespace.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (optional): Namespace (default: "default")

#### get_deployment
Get deployment details.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Deployment name

#### create_deployment
Create a new deployment.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Deployment name
  - `image` (required): Container image
  - `replicas` (optional): Number of replicas (default: 1)
  - `port` (optional): Container port
  - `env_vars` (optional): Environment variables object
  - `labels` (optional): Labels object

#### scale_deployment
Scale a deployment.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Deployment name
  - `replicas` (required): Desired replica count

#### update_deployment_image
Update deployment container image.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Deployment name
  - `container` (required): Container name
  - `image` (required): New image

#### restart_deployment
Restart a deployment by updating annotation.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Deployment name

#### delete_deployment
Delete a deployment.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Deployment name

### Service Management

#### list_services
List services in a namespace.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (optional): Namespace (default: "default")

#### create_service
Create a service for a deployment.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Service name
  - `selector` (required): Pod selector object
  - `ports` (required): Array of port mappings
  - `type` (optional): Service type (ClusterIP, NodePort, LoadBalancer)

#### delete_service
Delete a service.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Service name

### Ingress Management

#### list_ingresses
List ingress rules in a namespace.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (optional): Namespace (default: "default")

#### create_ingress
Create an ingress rule.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Ingress name
  - `rules` (required): Array of ingress rules
  - `tls` (optional): TLS configuration array

### ConfigMap Management

#### list_configmaps
List ConfigMaps in a namespace.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (optional): Namespace (default: "default")

#### create_configmap
Create a ConfigMap.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): ConfigMap name
  - `data` (required): Key-value data object

#### delete_configmap
Delete a ConfigMap.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): ConfigMap name

### Secret Management

#### list_secrets
List secrets in a namespace.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (optional): Namespace (default: "default")

#### create_secret
Create a secret (automatically base64 encodes).
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Secret name
  - `data` (required): Key-value data object
  - `type` (optional): Secret type (default: "Opaque")

#### delete_secret
Delete a secret.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): Secret name

### Storage Management

#### list_persistent_volumes
List PersistentVolumes in the cluster.
- **Parameters**:
  - `environment_id` (required): Target environment ID

#### list_persistent_volume_claims
List PersistentVolumeClaims in a namespace.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (optional): Namespace (default: "default")

#### create_persistent_volume_claim
Create a PersistentVolumeClaim.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): PVC name
  - `storage` (required): Storage size (e.g., "1Gi")
  - `access_modes` (optional): Array of access modes
  - `storage_class` (optional): Storage class name

#### delete_persistent_volume_claim
Delete a PersistentVolumeClaim.
- **Parameters**:
  - `environment_id` (required): Target environment ID
  - `namespace` (required): Namespace
  - `name` (required): PVC name

### Node Management

#### list_nodes
List cluster nodes with details.
- **Parameters**:
  - `environment_id` (required): Target environment ID

## Usage Examples

### Create and manage a deployment

```javascript
// Create a deployment
await use_mcp_tool("portainer-kubernetes", "create_deployment", {
  environment_id: "2",
  namespace: "production",
  name: "nginx-app",
  image: "nginx:latest",
  replicas: 3,
  port: 80,
  labels: { app: "nginx", tier: "frontend" }
});

// Scale the deployment
await use_mcp_tool("portainer-kubernetes", "scale_deployment", {
  environment_id: "2",
  namespace: "production",
  name: "nginx-app",
  replicas: 5
});

// Create a service for the deployment
await use_mcp_tool("portainer-kubernetes", "create_service", {
  environment_id: "2",
  namespace: "production",
  name: "nginx-service",
  selector: { app: "nginx" },
  ports: [{ port: 80, targetPort: 80 }],
  type: "LoadBalancer"
});
```

### Manage ConfigMaps and Secrets

```javascript
// Create a ConfigMap
await use_mcp_tool("portainer-kubernetes", "create_configmap", {
  environment_id: "2",
  namespace: "production",
  name: "app-config",
  data: {
    "app.properties": "debug=false\nport=8080",
    "database.conf": "host=db.example.com"
  }
});

// Create a Secret (automatically base64 encoded)
await use_mcp_tool("portainer-kubernetes", "create_secret", {
  environment_id: "2",
  namespace: "production",
  name: "db-credentials",
  data: {
    username: "dbuser",
    password: "secretpassword"
  }
});
```

### Storage operations

```javascript
// Create a PersistentVolumeClaim
await use_mcp_tool("portainer-kubernetes", "create_persistent_volume_claim", {
  environment_id: "2",
  namespace: "production",
  name: "data-storage",
  storage: "10Gi",
  access_modes: ["ReadWriteOnce"],
  storage_class: "fast-ssd"
});
```

### Pod troubleshooting

```javascript
// Get pod logs
await use_mcp_tool("portainer-kubernetes", "get_pod_logs", {
  environment_id: "2",
  namespace: "production",
  name: "nginx-app-7d9c5b5b6-abc123",
  tail_lines: 100
});

// Get pod details
await use_mcp_tool("portainer-kubernetes", "get_pod", {
  environment_id: "2",
  namespace: "production",
  name: "nginx-app-7d9c5b5b6-abc123"
});
```

## Error Handling

The server includes comprehensive error handling:
- Network timeouts and retries
- Invalid Kubernetes resource specifications
- Authentication failures
- Resource not found errors
- Namespace conflicts

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

## Security Notes

- The server automatically handles base64 encoding for Kubernetes secrets
- API tokens are never logged or exposed
- All communications use HTTPS when configured
- Follows Kubernetes RBAC permissions

## Troubleshooting

### Common Issues

1. **Authentication failures**: Ensure your API key is valid and has appropriate permissions
2. **Resource not found**: Verify the namespace and resource names
3. **Permission denied**: Check RBAC permissions for the service account
4. **Timeout errors**: Increase HTTP_TIMEOUT in environment variables

### 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+ with Kubernetes endpoints
- Valid Portainer API token
- Kubernetes cluster connected to Portainer