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:

   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_kubernetes_server.py
   

Configuration

Add to your Claude Desktop configuration:

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

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

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

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

// 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:

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