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

Clone this repository:

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

Install dependencies:

npm install

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:

Local Mode: Executes kubectl commands directly on the local machine
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