# manusa/kubernetes-mcp-server architecture

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

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

## Overview

Kubernetes MCP Server is a Go service that exposes Kubernetes and OpenShift operations to MCP clients. The principal workflow is an MCP request handled by the server, dispatched to enabled toolsets, and fulfilled through a cluster provider against Kubernetes APIs. Configuration, cluster targeting, HTTP/OAuth, and observability support that workflow. The README also documents Helm, Tekton, Kiali, KubeVirt, and network-observability capabilities; their paths are included from the tree, but unsampled internals are not assumed. Edges reflect excerpts or README statements; dashed links mark optional or unverified integrations.

Main entry points: [`pkg/mcp/mcp.go`](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/mcp/mcp.go) (MCP server), [`pkg/kubernetes-mcp-server/cmd/root.go`](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/kubernetes-mcp-server/cmd/root.go) (Server command), [`pkg/kubernetes/manager.go`](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/kubernetes/manager.go) (Cluster provider), [`pkg/toolsets/kiali/toolset.go`](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/kiali/toolset.go) (Kiali tools and prompts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_entry["CLI entry<br/>[main.go]"]
  node_command["Server command<br/>[root.go]"]
  node_mcp["MCP server<br/>[mcp.go]"]
  node_telemetry["Telemetry<br/>[telemetry.go]"]
end

subgraph group_cluster["Cluster access"]
  node_provider["Cluster provider<br/>[manager.go]"]
  node_kcp["KCP targets<br/>[provider.go]"]
end

subgraph group_operations["Kubernetes operations"]
  node_core["Core operations<br/>[toolset.go]"]
  node_helm["Helm operations<br/>[helm.go]"]
end

subgraph group_extensions["Domain extensions"]
  node_tekton["Tekton pipelines<br/>[pipeline.go]"]
  node_tektonrun["PipelineRun actions<br/>[pipelinerun.go]"]
  node_troubleshoot["Pipeline troubleshooting"]
  node_kiali["Kiali tools and prompts<br/>[toolset.go]"]
  node_kialiservice["Service diagnosis"]
  node_kubevirt["KubeVirt operations<br/>[toolset.go]"]
  node_netobserv["Network observability<br/>[toolset.go]"]
end

subgraph group_security["Configuration and security"]
  node_config["Configuration<br/>[config.go]"]
  node_http["HTTP and OAuth<br/>[authorization.go]"]
end

node_client(("MCP client"))
node_clusterapi(("Kubernetes API"))

node_client -->|"starts requests"| node_entry
node_entry -->|"executes"| node_command
node_command -->|"validates"| node_config
node_command -->|"starts"| node_mcp
node_command -->|"configures"| node_provider
node_command -->|"serves HTTP"| node_http
node_command -->|"initializes"| node_telemetry
node_mcp -->|"dispatches tools"| node_core
node_mcp -.->|"dispatches tools"| node_helm
node_mcp -.->|"dispatches tools"| node_tekton
node_mcp -.->|"dispatches tools"| node_kiali
node_mcp -.->|"dispatches tools"| node_kubevirt
node_mcp -.->|"dispatches tools"| node_netobserv
node_mcp -->|"uses targets"| node_provider
node_kcp -->|"builds managers"| node_provider
node_provider -.->|"connects to"| node_clusterapi
node_tekton -->|"creates PipelineRuns"| node_clusterapi
node_tektonrun -->|"reads and patches"| node_clusterapi
node_troubleshoot -->|"fetches run data"| node_clusterapi
node_kialiservice -->|"requests diagnostics"| node_kiali
node_kiali -.->|"returns results"| node_client

click node_entry "https://github.com/manusa/kubernetes-mcp-server/blob/main/cmd/kubernetes-mcp-server/main.go"
click node_command "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/kubernetes-mcp-server/cmd/root.go"
click node_mcp "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/mcp/mcp.go"
click node_config "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/config/config.go"
click node_http "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/http/authorization.go"
click node_provider "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/kubernetes/manager.go"
click node_kcp "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/kcp/provider.go"
click node_core "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/core/toolset.go"
click node_helm "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/helm/helm.go"
click node_tekton "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/tekton/pipeline.go"
click node_tektonrun "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/tekton/pipelinerun.go"
click node_troubleshoot "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/tekton/pipeline_troubleshoot.go"
click node_kiali "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/kiali/toolset.go"
click node_kialiservice "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/kiali/prompts/service_troubleshoot.go"
click node_kubevirt "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/kubevirt/toolset.go"
click node_netobserv "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/netobserv/toolset.go"
click node_telemetry "https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/telemetry/telemetry.go"

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_entry,node_command,node_mcp,node_telemetry,node_client toneBlue
class node_provider,node_kcp toneAmber
class node_core,node_helm,node_clusterapi toneMint
class node_tekton,node_tektonrun,node_troubleshoot,node_kiali,node_kialiservice,node_kubevirt,node_netobserv toneRose
class node_config,node_http toneIndigo
```

## Components

### Server runtime

- [CLI entry](https://github.com/manusa/kubernetes-mcp-server/blob/main/cmd/kubernetes-mcp-server/main.go): `cmd/kubernetes-mcp-server/main.go`
- [Server command](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/kubernetes-mcp-server/cmd/root.go): `pkg/kubernetes-mcp-server/cmd/root.go`
- [MCP server](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/mcp/mcp.go): `pkg/mcp/mcp.go`
- [Telemetry](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/telemetry/telemetry.go): `pkg/telemetry/telemetry.go`

### Cluster access

- [Cluster provider](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/kubernetes/manager.go): `pkg/kubernetes/manager.go`
- [KCP targets](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/kcp/provider.go): `pkg/kcp/provider.go`

### Kubernetes operations

- [Core operations](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/core/toolset.go): `pkg/toolsets/core/toolset.go`
- [Helm operations](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/helm/helm.go): `pkg/toolsets/helm/helm.go`

### Domain extensions

- [Tekton pipelines](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/tekton/pipeline.go): `pkg/toolsets/tekton/pipeline.go`
- [PipelineRun actions](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/tekton/pipelinerun.go): `pkg/toolsets/tekton/pipelinerun.go`
- [Pipeline troubleshooting](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/tekton/pipeline_troubleshoot.go): `pkg/toolsets/tekton/pipeline_troubleshoot.go`
- [Kiali tools and prompts](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/kiali/toolset.go): `pkg/toolsets/kiali/toolset.go`
- [Service diagnosis](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/kiali/prompts/service_troubleshoot.go): `pkg/toolsets/kiali/prompts/service_troubleshoot.go`
- [KubeVirt operations](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/kubevirt/toolset.go): `pkg/toolsets/kubevirt/toolset.go`
- [Network observability](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/toolsets/netobserv/toolset.go): `pkg/toolsets/netobserv/toolset.go`

### Configuration and security

- [Configuration](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/config/config.go): `pkg/config/config.go`
- [HTTP and OAuth](https://github.com/manusa/kubernetes-mcp-server/blob/main/pkg/http/authorization.go): `pkg/http/authorization.go`

### Other components

- **MCP client**
- **Kubernetes API**

## Connections

- MCP client → CLI entry: starts requests
- CLI entry → Server command: executes (evidence: `cmd/kubernetes-mcp-server/main.go`)
- Server command → Configuration: validates (evidence: `pkg/kubernetes-mcp-server/cmd/root.go`)
- Server command → MCP server: starts (evidence: `pkg/kubernetes-mcp-server/cmd/root.go`)
- Server command → Cluster provider: configures (evidence: `pkg/kubernetes-mcp-server/cmd/root.go`)
- Server command → HTTP and OAuth: serves HTTP (evidence: `pkg/kubernetes-mcp-server/cmd/root.go`)
- Server command → Telemetry: initializes (evidence: `pkg/kubernetes-mcp-server/cmd/root.go`)
- MCP server → Core operations: dispatches tools (evidence: `pkg/mcp/mcp.go`)
- MCP server → Helm operations: dispatches tools
- MCP server → Tekton pipelines: dispatches tools
- MCP server → Kiali tools and prompts: dispatches tools
- MCP server → KubeVirt operations: dispatches tools
- MCP server → Network observability: dispatches tools
- MCP server → Cluster provider: uses targets (evidence: `pkg/mcp/mcp.go`)
- KCP targets → Cluster provider: builds managers (evidence: `pkg/kcp/provider.go`)
- Cluster provider → Kubernetes API: connects to
- Tekton pipelines → Kubernetes API: creates PipelineRuns (evidence: `pkg/toolsets/tekton/pipeline.go`)
- PipelineRun actions → Kubernetes API: reads and patches (evidence: `pkg/toolsets/tekton/pipelinerun.go`)
- Pipeline troubleshooting → Kubernetes API: fetches run data (evidence: `pkg/toolsets/tekton/pipeline_troubleshoot.go`)
- Service diagnosis → Kiali tools and prompts: requests diagnostics (evidence: `pkg/toolsets/kiali/prompts/service_troubleshoot.go`)
- Kiali tools and prompts → MCP client: returns results
