# flux159/mcp-server-kubernetes architecture

> Architecture diagram of the GitHub repository flux159/mcp-server-kubernetes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/flux159/mcp-server-kubernetes
- Repository: https://github.com/flux159/mcp-server-kubernetes

## Overview

MCP Server Kubernetes exposes cluster-management tools, resources, and a troubleshooting prompt to MCP clients. The principal workflow is a client tool request, dispatch through the MCP server, execution by a Kubernetes or Helm operation, and interaction with the configured cluster. Separate tool families cover inspection, mutation, operations, and chart management; resource reads and the diagnostic prompt are additional product capabilities. Kubeconfig handling, command safeguards, and optional telemetry support the runtime. Several subsystem links reflect README capabilities whose implementation was not sampled; those links are limited to documented responsibilities.

Main entry points: [`src/index.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/index.ts) (MCP Entry), [`src/utils/kubernetes-manager.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/kubernetes-manager.ts) (Kubernetes Manager), [`src/tools/kubectl-get.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-get.ts) (Read and Inspect), [`src/tools/kubectl-context.ts`](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-context.ts) (Context Operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP Server"]
  node_server_entry["MCP Entry<br/>[index.ts]"]
  node_resource_handlers["Resource Handlers<br/>[handlers.ts]"]
  node_diagnostic_prompt["Diagnostic Prompt<br/>[index.ts]"]
end

subgraph group_cluster_access["Cluster Access"]
  node_manager["Kubernetes Manager"]
  node_kubeconfig["Kubeconfig Sources"]
  node_kubectl_cli["kubectl CLI"]
end

subgraph group_operations["Kubernetes Operations"]
  node_read_tools["Read and Inspect<br/>[kubectl-get.ts]"]
  node_describe_logs["Describe and Logs"]
  node_write_tools["Create and Apply<br/>[kubectl-apply.ts]"]
  node_delete_patch["Delete and Patch<br/>[kubectl-delete.ts]"]
  node_workload_ops["Workload Operations<br/>[kubectl-rollout.ts]"]
  node_context_ops["Context Operations<br/>[kubectl-context.ts]"]
  node_generic_ops["Generic kubectl<br/>[kubectl-generic.ts]"]
  node_helm_ops["Helm Operations<br/>[helm-operations.ts]"]
end

subgraph group_extensions["Product Extensions"]
  node_advanced_ops["Advanced Operations<br/>[node-management.ts]"]
  node_port_forward["Port Forwarding<br/>[port_forward.ts]"]
  node_pod_exec["Pod Execution<br/>[exec_in_pod.ts]"]
end

subgraph group_runtime_support["Runtime Support"]
  node_telemetry["Telemetry"]
  node_telemetry_middleware["Telemetry Middleware"]
  node_command_safety["Command Safeguards<br/>[kubectl-flags.ts]"]
  node_auth["HTTP Authentication<br/>[auth.ts]"]
end

node_client(("MCP Client"))
node_cluster[("Kubernetes Cluster")]
node_helm_cli["Helm CLI"]

node_client -->|"sends requests"| node_server_entry
node_server_entry -->|"registers resources"| node_resource_handlers
node_resource_handlers -->|"reads resources"| node_manager
node_server_entry -->|"registers prompt"| node_diagnostic_prompt
node_server_entry -->|"dispatches tools"| node_read_tools
node_server_entry -->|"dispatches tools"| node_describe_logs
node_server_entry -->|"dispatches tools"| node_write_tools
node_server_entry -->|"dispatches tools"| node_delete_patch
node_server_entry -->|"dispatches tools"| node_workload_ops
node_server_entry -->|"dispatches tools"| node_context_ops
node_server_entry -->|"dispatches tools"| node_generic_ops
node_server_entry -->|"dispatches tools"| node_helm_ops
node_server_entry -->|"dispatches tools"| node_advanced_ops
node_server_entry -->|"dispatches tools"| node_port_forward
node_server_entry -->|"dispatches tools"| node_pod_exec
node_manager -->|"loads configuration"| node_kubeconfig
node_manager -->|"uses Kubernetes API"| node_cluster
node_read_tools -->|"executes commands"| node_kubectl_cli
node_context_ops -->|"executes commands"| node_kubectl_cli
node_kubectl_cli -->|"queries or changes"| node_cluster
node_helm_ops -->|"runs operations"| node_helm_cli
node_helm_cli -->|"manages releases"| node_cluster
node_server_entry -->|"initializes"| node_telemetry
node_server_entry -.->|"uses instrumentation"| node_telemetry_middleware
node_read_tools -->|"validates arguments"| node_command_safety
node_context_ops -->|"executes safely"| node_command_safety
node_server_entry -.->|"HTTP requests"| node_auth

click node_server_entry "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/index.ts"
click node_resource_handlers "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/resources/handlers.ts"
click node_diagnostic_prompt "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/prompts/index.ts"
click node_manager "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/kubernetes-manager.ts"
click node_kubeconfig "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/kubernetes-manager.ts"
click node_read_tools "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-get.ts"
click node_describe_logs "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-describe.ts"
click node_write_tools "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-apply.ts"
click node_delete_patch "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-delete.ts"
click node_workload_ops "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-rollout.ts"
click node_context_ops "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-context.ts"
click node_generic_ops "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-generic.ts"
click node_helm_ops "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/helm-operations.ts"
click node_advanced_ops "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/node-management.ts"
click node_port_forward "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/port_forward.ts"
click node_pod_exec "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/exec_in_pod.ts"
click node_telemetry "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/config/telemetry-config.ts"
click node_telemetry_middleware "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/middleware/telemetry-middleware.ts"
click node_command_safety "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/security/kubectl-flags.ts"
click node_auth "https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/auth.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_entry,node_resource_handlers,node_diagnostic_prompt,node_client toneBlue
class node_manager,node_kubeconfig,node_kubectl_cli,node_cluster toneAmber
class node_read_tools,node_describe_logs,node_write_tools,node_delete_patch,node_workload_ops,node_context_ops,node_generic_ops,node_helm_ops toneMint
class node_advanced_ops,node_port_forward,node_pod_exec toneRose
class node_telemetry,node_telemetry_middleware,node_command_safety,node_auth,node_helm_cli toneIndigo
```

## Components

### MCP Server

- [MCP Entry](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/index.ts): `src/index.ts`
- [Resource Handlers](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/resources/handlers.ts): `src/resources/handlers.ts`
- [Diagnostic Prompt](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/prompts/index.ts): `src/prompts/index.ts`

### Cluster Access

- [Kubernetes Manager](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/kubernetes-manager.ts): `src/utils/kubernetes-manager.ts`
- [Kubeconfig Sources](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/kubernetes-manager.ts): `src/utils/kubernetes-manager.ts`
- **kubectl CLI**

### Kubernetes Operations

- [Read and Inspect](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-get.ts): `src/tools/kubectl-get.ts`
- [Describe and Logs](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-describe.ts): `src/tools/kubectl-describe.ts`
- [Create and Apply](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-apply.ts): `src/tools/kubectl-apply.ts`
- [Delete and Patch](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-delete.ts): `src/tools/kubectl-delete.ts`
- [Workload Operations](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-rollout.ts): `src/tools/kubectl-rollout.ts`
- [Context Operations](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-context.ts): `src/tools/kubectl-context.ts`
- [Generic kubectl](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/kubectl-generic.ts): `src/tools/kubectl-generic.ts`
- [Helm Operations](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/helm-operations.ts): `src/tools/helm-operations.ts`

### Product Extensions

- [Advanced Operations](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/node-management.ts): `src/tools/node-management.ts`
- [Port Forwarding](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/port_forward.ts): `src/tools/port_forward.ts`
- [Pod Execution](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/tools/exec_in_pod.ts): `src/tools/exec_in_pod.ts`

### Runtime Support

- [Telemetry](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/config/telemetry-config.ts): `src/config/telemetry-config.ts`
- [Telemetry Middleware](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/middleware/telemetry-middleware.ts): `src/middleware/telemetry-middleware.ts`
- [Command Safeguards](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/security/kubectl-flags.ts): `src/security/kubectl-flags.ts`
- [HTTP Authentication](https://github.com/flux159/mcp-server-kubernetes/blob/main/src/utils/auth.ts): `src/utils/auth.ts`

### Other components

- **MCP Client**
- **Kubernetes Cluster**
- **Helm CLI**

## Connections

- MCP Client → MCP Entry: sends requests
- MCP Entry → Resource Handlers: registers resources
- Resource Handlers → Kubernetes Manager: reads resources
- MCP Entry → Diagnostic Prompt: registers prompt
- MCP Entry → Read and Inspect: dispatches tools
- MCP Entry → Describe and Logs: dispatches tools
- MCP Entry → Create and Apply: dispatches tools
- MCP Entry → Delete and Patch: dispatches tools
- MCP Entry → Workload Operations: dispatches tools
- MCP Entry → Context Operations: dispatches tools
- MCP Entry → Generic kubectl: dispatches tools
- MCP Entry → Helm Operations: dispatches tools
- MCP Entry → Advanced Operations: dispatches tools
- MCP Entry → Port Forwarding: dispatches tools
- MCP Entry → Pod Execution: dispatches tools
- Kubernetes Manager → Kubeconfig Sources: loads configuration
- Kubernetes Manager → Kubernetes Cluster: uses Kubernetes API
- Read and Inspect → kubectl CLI: executes commands
- Context Operations → kubectl CLI: executes commands
- kubectl CLI → Kubernetes Cluster: queries or changes
- Helm Operations → Helm CLI: runs operations
- Helm CLI → Kubernetes Cluster: manages releases
- MCP Entry → Telemetry: initializes
- MCP Entry → Telemetry Middleware: uses instrumentation
- Read and Inspect → Command Safeguards: validates arguments
- Context Operations → Command Safeguards: executes safely
- MCP Entry → HTTP Authentication: HTTP requests