Kubernetes and Helm MCP Server Guide

kubectl cluster-info

# rbac-mcp-readonly.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: mcp-cluster-reader
  namespace: default
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: mcp-readonly-role
rules:
  - apiGroups: ["", "apps", "batch"]
    resources: ["pods", "pods/log", "deployments", "statefulsets", "daemonsets", "jobs", "services", "events"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: [] # Explicitly deny secret inspection
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: mcp-readonly-binding
subjects:
  - kind: ServiceAccount
    name: mcp-cluster-reader
    namespace: default
roleRef:
  kind: ClusterRole
  name: mcp-readonly-role
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f rbac-mcp-readonly.yaml

{
  "mcpServers": {
    "kubernetes-ops": {
      "command": "node",
      "args": ["/opt/mcp-servers/kubernetes/dist/index.js"],
      "env": {
        "KUBECONFIG": "/Users/developer/.kube/config",
        "DEFAULT_NAMESPACE": "production"
      }
    }
  }
}

{
  "mcpServers": {
    "kubernetes-ops": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "KUBECONFIG": "/Users/developer/.kube/config"
      }
    }
  }
}

[mcp_servers.kubernetes_ops]
command = "node"
args = ["/opt/mcp-servers/kubernetes/dist/index.js"]

[mcp_servers.kubernetes_ops.env]
KUBECONFIG = "/home/developer/.kube/config"
DEFAULT_NAMESPACE = "default"

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import * as k8s from '@kubernetes/client-node';
import { execFile } from 'child_process';
import { promisify } from 'util';

const execFileAsync = promisify(execFile);

const kc = new k8s.KubeConfig();
kc.loadFromDefault();

const k8sCoreApi = kc.makeApiClient(k8s.CoreV1Api);
const k8sAppsApi = kc.makeApiClient(k8s.AppsV1Api);

const server = new Server(
  { name: 'kubernetes-helm-mcp', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: 'list_pods_in_namespace',
        description: 'List pods and their current phase (Running, CrashLoopBackOff, Pending) in a given namespace.',
        inputSchema: {
          type: 'object',
          properties: {
            namespace: { type: 'string', default: 'default', description: 'Target Kubernetes namespace' }
          }
        }
      },
      {
        name: 'get_pod_logs_tail',
        description: 'Fetch the most recent stdout and stderr log lines (maximum 100) from a specific container.',
        inputSchema: {
          type: 'object',
          properties: {
            pod_name: { type: 'string', description: 'Name of the pod' },
            namespace: { type: 'string', default: 'default', description: 'Namespace' },
            tail_lines: { type: 'number', default: 50, maximum: 100, description: 'Number of recent lines to retrieve' }
          },
          required: ['pod_name']
        }
      },
      {
        name: 'list_helm_releases',
        description: 'List deployed Helm chart releases, status, revision, and chart versions across a namespace.',
        inputSchema: {
          type: 'object',
          properties: {
            namespace: { type: 'string', default: 'default', description: 'Target namespace' }
          }
        }
      }
    ]
  };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  try {
    if (name === 'list_pods_in_namespace') {
      const ns = (args?.namespace as string) || 'default';
      const res = await k8sCoreApi.listNamespacedPod({ namespace: ns });

      const podSummaries = res.items.map(pod => ({
        name: pod.metadata?.name,
        phase: pod.status?.phase,
        restarts: pod.status?.containerStatuses?.[0]?.restartCount ?? 0,
        age: pod.metadata?.creationTimestamp
      }));

      return {
        content: [{ type: 'text', text: JSON.stringify(podSummaries, null, 2) }]
      };
    }

    if (name === 'get_pod_logs_tail') {
      const podName = args?.pod_name as string;
      const ns = (args?.namespace as string) || 'default';
      const tailLines = Math.min(Number(args?.tail_lines) || 50, 100);

      const logsRes = await k8sCoreApi.readNamespacedPodLog({
        name: podName,
        namespace: ns,
        tailLines: tailLines
      });

      return {
        content: [{ type: 'text', text: String(logsRes) }]
      };
    }

    if (name === 'list_helm_releases') {
      const ns = (args?.namespace as string) || 'default';
      const { stdout } = await execFileAsync('helm', ['list', '-n', ns, '-o', 'json']);
      const parsed = JSON.parse(stdout || '[]');

      return {
        content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }]
      };
    }

    throw new Error(`Tool '${name}' is not recognized.`);
  } catch (err: any) {
    return {
      isError: true,
      content: [{ type: 'text', text: `Kubernetes API Error: ${err.message}` }]
    };
  }
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch((err) => {
  process.stderr.write(`Fatal server error: ${err.message}\n`);
  process.exit(1);
});

{
  "jsonrpc": "2.0",
  "id": "k8s-pod-list-01",
  "method": "tools/call",
  "params": {
    "name": "list_pods_in_namespace",
    "arguments": {
      "namespace": "production"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "k8s-pod-list-01",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[\n  {\"name\": \"auth-service-78f9d-jk41\", \"phase\": \"Running\", \"restarts\": 0},\n  {\"name\": \"billing-worker-41a2c-99zx\", \"phase\": \"CrashLoopBackOff\", \"restarts\": 14}\n]"
      }
    ]
  }
}