Kubernetes MCP Server

A Model Context Protocol (MCP) server that provides comprehensive Kubernetes cluster management capabilities. This server enables AI assistants like Claude to interact with Kubernetes clusters through 50 specialized tools, supporting both local kubectl and remote SSH-based execution.

Features

50 Kubernetes Management Tools

This MCP server provides complete cluster management capabilities organized into the following categories:

Cluster Management (4 tools)

• k8s_get_cluster_info - Get cluster information including server version and endpoints
• k8s_list_nodes - List all nodes with status, roles, and resource information
• k8s_get_node - Get detailed information about a specific node
• k8s_describe_node - Get full node description including conditions and capacity

Namespace Management (3 tools)

• k8s_list_namespaces - List all namespaces in the cluster
• k8s_create_namespace - Create a new namespace
• k8s_delete_namespace - Delete a namespace (with warning)

Pod Management (6 tools)

• k8s_list_pods - List pods with filtering by namespace and labels
• k8s_get_pod - Get detailed pod information
• k8s_describe_pod - Get full pod description including events
• k8s_get_pod_logs - Get container logs with filtering options
• k8s_delete_pod - Delete a pod (with optional force)
• k8s_exec_pod - Execute commands in pod containers

Deployment Management (6 tools)

• k8s_list_deployments - List deployments in namespace or cluster-wide
• k8s_get_deployment - Get detailed deployment information
• k8s_describe_deployment - Get full deployment description with events
• k8s_scale_deployment - Scale deployment replicas
• k8s_restart_deployment - Perform rolling restart
• k8s_update_deployment_image - Update container image

Service Management (3 tools)

• k8s_list_services - List services in namespace or cluster-wide
• k8s_get_service - Get detailed service information
• k8s_describe_service - Get full service description including endpoints

ConfigMap Management (4 tools)

• k8s_list_configmaps - List ConfigMaps in namespace
• k8s_get_configmap - Get ConfigMap details and data
• k8s_create_configmap - Create ConfigMap from literal values
• k8s_delete_configmap - Delete a ConfigMap

Secret Management (4 tools)

• k8s_list_secrets - List secrets (values hidden)
• k8s_get_secret - Get secret metadata (with optional decode)
• k8s_create_secret - Create secret from literal values
• k8s_delete_secret - Delete a secret

StatefulSet Management (3 tools)

• k8s_list_statefulsets - List StatefulSets in namespace
• k8s_get_statefulset - Get StatefulSet details
• k8s_scale_statefulset - Scale StatefulSet replicas

DaemonSet Management (2 tools)

• k8s_list_daemonsets - List DaemonSets in namespace
• k8s_get_daemonset - Get DaemonSet details

Ingress Management (2 tools)

• k8s_list_ingresses - List Ingresses in namespace
• k8s_get_ingress - Get Ingress details

Resource Management (5 tools)

• k8s_apply_manifest - Apply YAML/JSON manifest to cluster
• k8s_delete_resource - Delete resource by type and name
• k8s_get_events - Get cluster events with optional filtering
• k8s_get_resource_yaml - Get any resource as YAML
• k8s_get_all - Get all common resources in namespace

Rollout Management (3 tools)

• k8s_rollout_status - Get deployment rollout status
• k8s_rollout_history - Get rollout history
• k8s_rollout_undo - Undo deployment rollout

Metrics & Monitoring (2 tools)

• k8s_top_nodes - Show node resource usage (CPU/memory)
• k8s_top_pods - Show pod resource usage (CPU/memory)

Context Management (2 tools)

• k8s_get_contexts - List all available kubectl contexts
• k8s_current_context - Get current kubectl context

Installation

Prerequisites

• Node.js 20 or higher
• TypeScript 5.3 or higher
• kubectl installed and configured (for local mode)
• SSH access configured (for remote mode)

Setup

1. Clone this repository:

git clone https://github.com/yourusername/mcp-kubernetes.git
cd mcp-kubernetes

2. Install dependencies:

npm install

3. Build the TypeScript source:

npm run build

Configuration

Environment Variables

The server supports both local kubectl execution and remote SSH-based execution:

Local kubectl Mode

• KUBECONFIG (optional) - Path to kubeconfig file (defaults to ~/.kube/config)
• K8S_CONTEXT (optional) - Specific kubectl context to use
• K8S_DEFAULT_NAMESPACE (optional) - Default namespace (defaults to "default")
• KUBECTL_PATH (optional) - Path to kubectl binary (defaults to "kubectl")

Remote SSH Mode (for K3s or remote clusters)

• K8S_SSH_HOST - SSH host for remote kubectl execution (e.g., 192.168.16.100)
• K8S_SSH_USER - SSH username for authentication
• K8S_SSH_KEY - Path to SSH private key for authentication
• K8S_SSH_PASSWORD (alternative) - SSH password (uses plink on Windows, sshpass on Linux)
• K8S_DEFAULT_NAMESPACE (optional) - Default namespace (defaults to "default")

Claude Desktop Configuration

Add to your Claude desktop configuration file (~/.claude/config.json or %APPDATA%\Claude\config.json on Windows):

Local kubectl:

{
  "mcpServers": {
    "kubernetes": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-kubernetes/dist/index.js"],
      "env": {
        "K8S_DEFAULT_NAMESPACE": "default"
      }
    }
  }
}

Remote SSH (K3s/Raspberry Pi example):

{
  "mcpServers": {
    "kubernetes": {
      "type": "stdio",
      "command": "node",
      "args": ["C:/Users/Administrator/mcp-servers/kubernetes/dist/index.js"],
      "env": {
        "K8S_SSH_HOST": "192.168.16.100",
        "K8S_SSH_USER": "mark",
        "K8S_SSH_KEY": "C:/Users/Administrator/.ssh/id_ed25519_k8s",
        "K8S_DEFAULT_NAMESPACE": "default"
      }
    }
  }
}

Usage Examples

List all pods in a namespace

// Using the k8s_list_pods tool
{
  "namespace": "default"
}

Get pod logs

// Using the k8s_get_pod_logs tool
{
  "name": "my-pod",
  "namespace": "default",
  "tail": 100,
  "since": "5m"
}

Scale a deployment

// Using the k8s_scale_deployment tool
{
  "name": "my-deployment",
  "namespace": "default",
  "replicas": 3
}

Apply a manifest

// Using the k8s_apply_manifest tool
{
  "manifest": "apiVersion: v1\nkind: Pod\n...",
  "namespace": "default"
}

Execute command in pod

// Using the k8s_exec_pod tool
{
  "name": "my-pod",
  "namespace": "default",
  "command": "ls -la /app"
}

Get cluster events

// Using the k8s_get_events tool
{
  "namespace": "default"
}

Development

Running in development mode

npm run dev

Building for production

npm run build

Starting the server

npm start

Architecture

The server uses the Model Context Protocol (MCP) to expose Kubernetes operations as tools. It supports two execution modes:

1. Local Mode: Executes kubectl commands directly on the local machine
2. Remote SSH Mode: Executes kubectl commands on a remote server via SSH (useful for K3s clusters or remote Kubernetes installations)

The server automatically detects which mode to use based on the presence of SSH environment variables.

Use Cases

• Raspberry Pi K3s Clusters: Manage lightweight K3s clusters remotely
• Development Clusters: Quick operations on local development clusters
• Production Monitoring: Read-only operations for cluster health monitoring
• GitOps Workflows: Apply manifests and track deployments
• Troubleshooting: Get logs, describe resources, check events
• Resource Management: Create/delete ConfigMaps, Secrets, and other resources

Security Considerations

• SSH Key Authentication: Prefer SSH key authentication over password-based auth
• Read-Only Operations: Many tools are read-only and safe for production
• Secret Handling: Secrets are base64 encoded by default; decode only when necessary
• Namespace Isolation: Use namespace parameters to limit scope of operations
• Force Operations: Be cautious with force parameters on delete operations

Tested Environments

• K3s on Raspberry Pi (v1.33.5+k3s1)
• Local Kubernetes (minikube, kind, Docker Desktop)
• Remote Kubernetes via SSH

Limitations

• Requires kubectl to be installed and accessible
• SSH mode requires sudo access for kubectl on remote host
• Metrics tools require metrics-server to be installed in the cluster
• Windows SSH password auth requires PuTTY's plink to be available

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details

Acknowledgments

• Built with the Model Context Protocol SDK
• Designed for use with Claude Desktop
• Inspired by the Kubernetes community's kubectl tool

Support

For issues, questions, or contributions, please open an issue on GitHub.

Version History

• 1.0.0 - Initial release with 50 Kubernetes management tools
  • Full support for pods, deployments, services, ConfigMaps, secrets
  • StatefulSets, DaemonSets, Ingresses
  • Rollout management and metrics
  • Local and remote SSH execution modes