Helm Install - cturner8/kube-mcp GitHub Wiki

The recommended deployment method is using Helm. This provides a production-ready deployment with sensible defaults and extensive configuration options.

Published Artifacts

Both the application container image and Helm chart are published to the GitHub Container Registry (ghcr.io):

  • Container Image: ghcr.io/cturner8/kube-mcp
    • Multi-architecture support (amd64, arm64)
    • Runs as non-root user (UID 10001)
    • Read-only root filesystem for security
  • Helm Chart: ghcr.io/cturner8/kube-mcp-chart
    • OCI-compatible Helm chart
    • Includes RBAC, ServiceAccount, Deployment, Service, and optional Ingress resources

Prerequisites

Before installing kube-mcp, ensure you have:

  • Kubernetes cluster (v1.19+)
  • Helm 3.8+
  • OIDC provider configured with a registered client application
  • (Optional) Ingress controller if you plan to expose the service externally

Quickstart

While the Helm chart can be installed without any custom values, it is strongly recommended to configure at least the MCP server settings and OIDC authentication.

Step 1: Create a values file

Create a values.yaml file with your configuration:

mcp:
  # The externally accessible URL where clients will connect
  baseUrl: "https://mcp.example.com"

  # OIDC authentication configuration
  oidc:
    issuerUrl: "https://auth.example.com"
    clientId: "00000000-0000-0000-0000-000000000000"
    signingMethod: "RS256" # RS256 (default) or HS256
    scopes: "openid,profile,email"

  # Optional: Tool access restrictions
  tools:
    # Disallow sensitive tools by default (recommended)
    disallowed: "list_secrets,list_config_maps,get_secret,get_config_map"
    # Or use 'allowed' to explicitly whitelist tools
    # allowed: "list_pods,get_pod,list_deployments"

# Enable ingress for external access
ingress:
  enabled: true
  className: "nginx" # or your ingress class
  hosts:
    - host: mcp.example.com
      paths:
        - path: /
          pathType: Prefix
  # Optional: TLS configuration
  tls:
    - secretName: mcp-tls
      hosts:
        - mcp.example.com

Step 2: Install the chart

Install the chart using Helm:

# Install in the default namespace
helm install kube-mcp oci://ghcr.io/cturner8/kube-mcp-chart -f values.yaml

# Or install in a specific namespace
helm install kube-mcp oci://ghcr.io/cturner8/kube-mcp-chart \
  --namespace kube-mcp \
  --create-namespace \
  -f values.yaml

Tip: For reproducible deployments, pin to a specific chart version:

helm install kube-mcp oci://ghcr.io/cturner8/kube-mcp-chart --version 1.0.0 -f values.yaml

View available versions at ghcr.io/cturner8/kube-mcp-chart.

Step 3: Verify the deployment

Check the deployment status:

# Check pod status
kubectl get pods -l app.kubernetes.io/name=kube-mcp-chart

# Check service
kubectl get svc -l app.kubernetes.io/name=kube-mcp-chart

# View logs
kubectl logs -l app.kubernetes.io/name=kube-mcp-chart

Upgrading

To upgrade an existing installation:

helm upgrade kube-mcp oci://ghcr.io/cturner8/kube-mcp-chart -f values.yaml

Uninstalling

To remove the deployment:

helm uninstall kube-mcp

Configuration

See Configuration Options for all available Helm values and detailed configuration guidance.

Troubleshooting

Pod fails to start

Check the pod logs for errors:

kubectl logs -l app.kubernetes.io/name=kube-mcp-chart

Common issues:

  • Invalid OIDC configuration (check issuerUrl and clientId)
  • RBAC permissions not configured correctly
  • Network connectivity to OIDC issuer

Authentication failures

Verify your OIDC configuration:

# Check the PRM endpoint
curl https://mcp.example.com/.well-known/oauth-protected-resource

# Verify OIDC discovery
curl https://auth.example.com/.well-known/openid-configuration