Architecture - mcp-server-kubernetes

Executive Summary

An MCP (Model Context Protocol) server that provides AI assistants with comprehensive Kubernetes cluster management capabilities. Built with the official Kubernetes client-node library and MCP SDK, it exposes eight tools for listing pods, deployments, and services, retrieving pod logs, applying manifests, listing namespaces, getting cluster events, and scaling deployments. The server uses kubeconfig or in-cluster authentication and communicates via stdio transport for integration with Claude Desktop and other MCP clients.

Overview

TypeScript

Language

MCP Server

Architecture Diagram

MCP Client
Claude Desktop / AI Assistant

stdio Transport
JSON-RPC over stdin/stdout

MCP Server Entry
src/index.ts

<-->

Kube Config Loader
src/kube.ts

Tool Dispatch Layer

list_pods
Core v1

list_deployments
Apps v1

list_services
Core v1

get_pod_logs
Core v1

apply_manifest
Dynamic

list_namespaces
Core v1

get_events
Core v1

scale_deployment
Apps v1

Kubernetes API Server
Cluster Control Plane

Pods

Deployments

Services

Namespaces

Events

Component Breakdown

Component	File	Purpose	Key Dependencies
Server Entry	`src/index.ts`	MCP server initialization, tool registration, stdio transport	@modelcontextprotocol/sdk
Kube Config	`src/kube.ts`	Kubernetes client configuration (kubeconfig or in-cluster)	@kubernetes/client-node
List Pods	`src/tools/list_pods.ts`	List pods with namespace and label selector filtering	CoreV1Api
List Deployments	`src/tools/list_deployments.ts`	List deployments with optional namespace filtering	AppsV1Api
List Services	`src/tools/list_services.ts`	List services with optional namespace filtering	CoreV1Api
Get Pod Logs	`src/tools/get_pod_logs.ts`	Retrieve pod logs with container and tail line options	CoreV1Api
Apply Manifest	`src/tools/apply_manifest.ts`	Apply a YAML manifest to the cluster	KubernetesObjectApi, yaml
List Namespaces	`src/tools/list_namespaces.ts`	List all namespaces in the cluster	CoreV1Api
Get Events	`src/tools/get_events.ts`	Get cluster events with optional namespace filtering	CoreV1Api
Scale Deployment	`src/tools/scale_deployment.ts`	Scale a deployment to a specified replica count	AppsV1Api

Data Flow / Request Flow

Client Request -- An MCP client sends a JSON-RPC tool invocation over stdio with tool name and parameters.
Parameter Validation -- Parameters are validated using Zod schemas specific to each tool.
Kube Auth -- The kube config loader resolves authentication from kubeconfig file or in-cluster service account.
API Call -- The tool handler uses the Kubernetes client-node library to call the cluster API server.
Response Formatting -- Kubernetes API responses are serialized and returned to the MCP client as structured content.

Security Controls

Control	Implementation
Authentication	Kubeconfig file or in-cluster service account token
RBAC	Kubernetes RBAC controls which resources the service account can access
Input Validation	Zod schema validation on all tool parameters; YAML parsing for manifests
Transport Security	TLS for Kubernetes API server communication; stdio for local MCP transport
Namespace Isolation	Tools support namespace filtering to restrict operations
Manifest Validation	YAML manifests are parsed and validated before application

Industry Adaptation

Healthcare

Monitor HIPAA-compliant workloads on AKS/EKS/GKE, scale healthcare applications, retrieve pod logs for compliance auditing.

Finance

Manage PCI-DSS scoped Kubernetes workloads, monitor deployment status for financial applications, audit cluster events.

DevOps

Deployment management, pod troubleshooting via logs, manifest application for GitOps workflows, auto-scaling operations.

Platform Engineering

Multi-cluster management, namespace provisioning, event monitoring for platform health, deployment scaling for capacity management.

Production Readiness Checklist

Configure kubeconfig or in-cluster service account with minimum RBAC permissions
Build TypeScript to JavaScript (npm run build)
Test all eight tools against target Kubernetes cluster
Configure MCP client with server entry point
Set up Kubernetes audit logging for API access tracking
Create dedicated service account with namespace-scoped RBAC
Deploy as Docker container or in-cluster pod
Monitor Kubernetes API server audit logs

Configuration / Environment Variables

Variable	Required	Default	Description
`KUBECONFIG`	No	~/.kube/config	Path to kubeconfig file (auto-detected in-cluster)

Deployment

Local Development

git clone https://github.com/kogunlowo123/mcp-server-kubernetes.git
cd mcp-server-kubernetes
npm install
npm run build
npm start

Docker / Production

docker build -t mcp-server-kubernetes .
docker run \
  -v ~/.kube/config:/root/.kube/config:ro \
  mcp-server-kubernetes

Links

Repository	github.com/kogunlowo123/mcp-server-kubernetes
README	README.md
Changelog	CHANGELOG.md
License	MIT License