mcp-kubernetes

README

mcp-kubernetes

A Model Context Protocol (MCP) server that provides tools for interacting with Kubernetes clusters.

Features

• Resource Management: Get, list, describe, create, apply, delete, and patch Kubernetes resources
• Pod Operations: Get logs, execute commands, and set up port forwarding
• Context Management: List, get, and switch between Kubernetes contexts
• Cluster Information: Get API resources and cluster health status
• Multiple Authentication Modes: Support for kubeconfig, in-cluster, and OAuth 2.1 authentication
• Multiple Transport Types: Support for stdio, SSE, and streamable HTTP
• Safety Features: Non-destructive mode, dry-run capability, and operation restrictions
• OAuth 2.1 Support: Secure token-based authentication with Dex OIDC (default) and Google OAuth providers
• Production-Grade Observability: OpenTelemetry instrumentation with Prometheus metrics and distributed tracing

Installation

go install github.com/giantswarm/mcp-kubernetes@latest

Usage

Basic Usage

# Start the MCP server with default settings (stdio transport, kubeconfig authentication)
mcp-kubernetes serve

# Start with debug logging
mcp-kubernetes serve --debug

# Start with in-cluster authentication (when running as a pod in Kubernetes)
mcp-kubernetes serve --in-cluster

Authentication Modes

The server supports two authentication modes:

Kubeconfig Authentication (Default)

Uses standard kubeconfig file authentication. The server will look for kubeconfig in the default locations (~/.kube/config) or use the KUBECONFIG environment variable.

# Use default kubeconfig
mcp-kubernetes serve

# Use specific kubeconfig (via environment variable)
KUBECONFIG=/path/to/kubeconfig mcp-kubernetes serve

In-Cluster Authentication

Uses service account token when running inside a Kubernetes pod. This mode automatically uses the mounted service account credentials.

# Enable in-cluster authentication
mcp-kubernetes serve --in-cluster

Requirements for in-cluster mode:

• Must be running inside a Kubernetes pod
• Service account token must be mounted at /var/run/secrets/kubernetes.io/serviceaccount/token
• CA certificate must be available at /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
• Namespace must be available at /var/run/secrets/kubernetes.io/serviceaccount/namespace

OAuth 2.1 Authentication

Uses OAuth 2.1 with Dex OIDC (default) or Google OAuth provider for secure, token-based authentication (available for HTTP transports only).

# Start with Dex OAuth authentication (default provider)
mcp-kubernetes serve \
  --transport=streamable-http \
  --enable-oauth \
  --oauth-base-url=https://mcp.example.com \
  --dex-issuer-url=https://dex.example.com \
  --dex-client-id=mcp-kubernetes \
  --dex-client-secret=YOUR_DEX_SECRET \
  --dex-connector-id=github \
  --registration-token=YOUR_SECURE_TOKEN

# Or use Google OAuth provider
mcp-kubernetes serve \
  --transport=streamable-http \
  --enable-oauth \
  --oauth-provider=google \
  --oauth-base-url=https://mcp.example.com \
  --google-client-id=YOUR_CLIENT_ID \
  --google-client-secret=YOUR_CLIENT_SECRET \
  --registration-token=YOUR_SECURE_TOKEN

See docs/oauth.md for detailed OAuth setup and configuration.

Observability

The server includes comprehensive OpenTelemetry instrumentation for production monitoring:

• Metrics: Prometheus-compatible metrics for HTTP requests, Kubernetes operations, and sessions
• Distributed Tracing: OpenTelemetry traces for request flows and K8s API calls
• Metrics Endpoint: /metrics endpoint for Prometheus scraping

# Enable instrumentation (enabled by default)
INSTRUMENTATION_ENABLED=true

# Configure metrics exporter (prometheus, otlp, stdout)
METRICS_EXPORTER=prometheus

# Configure tracing exporter (otlp, stdout, none)
TRACING_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

# Set trace sampling rate (0.0 to 1.0)
OTEL_TRACES_SAMPLER_ARG=0.1

Available Metrics:

• http_requests_total - HTTP request counter
• http_request_duration_seconds - HTTP request duration histogram
• kubernetes_operations_total - Kubernetes operation counter
• kubernetes_operation_duration_seconds - K8s operation duration histogram
• kubernetes_pod_operations_total - Pod operation counter
• oauth_downstream_auth_total - OAuth authentication counter
• active_port_forward_sessions - Active port-forward sessions gauge

See docs/observability.md for detailed metrics documentation, Prometheus queries, and alerting examples.

Transport Types

Standard I/O (Default)

mcp-kubernetes serve --transport stdio

Server-Sent Events (SSE)

mcp-kubernetes serve --transport sse --http-addr :8080

Streamable HTTP

mcp-kubernetes serve --transport streamable-http --http-addr :8080

Configuration Options

# Safety and operation modes
--non-destructive     # Enable non-destructive mode (default: true)
--dry-run            # Enable dry run mode (default: false)

# Performance tuning
--qps-limit 20.0     # QPS limit for Kubernetes API calls
--burst-limit 30     # Burst limit for Kubernetes API calls

# Authentication
--in-cluster                   # Use in-cluster authentication instead of kubeconfig
--enable-oauth                 # Enable OAuth 2.1 authentication (for HTTP transports)
--oauth-base-url string        # OAuth base URL (e.g., https://mcp.example.com)
--google-client-id string      # Google OAuth Client ID
--google-client-secret string  # Google OAuth Client Secret
--registration-token string    # OAuth client registration access token
--allow-public-registration    # Allow unauthenticated OAuth client registration

# Debugging
--debug              # Enable debug logging

# Transport-specific options
--transport string            # Transport type: stdio, sse, or streamable-http
--http-addr :8080            # HTTP server address (for sse and streamable-http)
--sse-endpoint /sse          # SSE endpoint path
--message-endpoint /message  # Message endpoint path
--http-endpoint /mcp         # HTTP endpoint path
--disable-streaming          # Disable streaming for streamable-http transport

Running in Kubernetes

To run mcp-kubernetes as a pod in your Kubernetes cluster:

1. Create RBAC Resources

apiVersion: v1
kind: ServiceAccount
metadata:
  name: mcp-kubernetes
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: mcp-kubernetes
rules:
- apiGroups: [""]
  resources: ["*"]
  verbs: ["get", "list", "create", "update", "patch", "delete"]
- apiGroups: ["apps"]
  resources: ["*"]
  verbs: ["get", "list", "create", "update", "patch", "delete"]
- apiGroups: ["batch"]
  resources: ["*"]
  verbs: ["get", "list", "create", "update", "patch", "delete"]
# Add more API groups as needed
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: mcp-kubernetes
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: mcp-kubernetes
subjects:
- kind: ServiceAccount
  name: mcp-kubernetes
  namespace: default

2. Create Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-kubernetes
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mcp-kubernetes
  template:
    metadata:
      labels:
        app: mcp-kubernetes
    spec:
      serviceAccountName: mcp-kubernetes
      containers:
      - name: mcp-kubernetes
        image: ghcr.io/giantswarm/mcp-kubernetes:latest
        args:
        - "serve"
        - "--in-cluster"
        - "--transport=sse"
        - "--http-addr=:8080"
        ports:
        - containerPort: 8080
          name: http
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 512Mi

Available Tools

The MCP server provides the following tools:

Resource Management

• k8s_get_resource - Get a specific resource
• k8s_list_resources - List resources with pagination
• k8s_describe_resource - Get detailed resource information
• k8s_create_resource - Create a new resource
• k8s_apply_resource - Apply resource configuration
• k8s_delete_resource - Delete a resource
• k8s_patch_resource - Patch a resource
• k8s_scale_resource - Scale deployments, replicasets, statefulsets

Pod Operations

• k8s_get_pod_logs - Get logs from pod containers
• k8s_exec_pod - Execute commands in pod containers
• k8s_port_forward_pod - Set up port forwarding to pods
• k8s_port_forward_service - Set up port forwarding to services

Context Management

• k8s_list_contexts - List available Kubernetes contexts
• k8s_get_current_context - Get the current context
• k8s_switch_context - Switch to a different context

Cluster Information

• k8s_get_api_resources - Get available API resources
• k8s_get_cluster_health - Get cluster health information

Development

Building

make build

Testing

make test

Linting

make lint

Security

Authentication & Authorization

• The server runs in non-destructive mode by default
• Supports dry-run mode for safe operation testing
• Allows restriction of operations and namespaces
• Follows Kubernetes RBAC when using in-cluster authentication
• OAuth 2.1 support with PKCE enforcement for HTTP transports
• Downstream OAuth authentication for per-user RBAC enforcement

Secret Management (CRITICAL for Production)

⚠️ PRODUCTION REQUIREMENT: You MUST use a secret management solution for production deployments.

Recommended Solutions:

• HashiCorp Vault
• AWS Secrets Manager
• Google Cloud Secret Manager
• Azure Key Vault
• Kubernetes External Secrets Operator

NEVER use environment variables for secrets in production because they:

• Are visible in process listings (ps aux, docker inspect)
• Get leaked in logs and error messages
• Have no audit trail or rotation support
• Are not encrypted at rest
• Cannot be securely deleted

For detailed setup and examples, see:

• OAuth Authentication Guide
• Production Security Checklist
• Incident Response Procedures

Security Best Practices

Development:

• Use environment variables only for local development
• Never commit secrets to Git
• Use pre-commit hooks (gitleaks, git-secrets)
• Generate secrets securely (avoid shell history)

Production:

• Store secrets in a secret manager (required)
• Enable encryption at rest for Kubernetes Secrets
• Rotate encryption keys every 90 days
• Enable audit logging and monitoring
• Use HTTPS with valid TLS certificates
• Follow the comprehensive production checklist

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.