MCP Server: Go Kubernetes Pods, Logs, Namespaces

Overview

MCP Server is a small Go-based HTTP service that makes Kubernetes pods, logs, events and namespaces easy to browse and query. It connects to the Kubernetes API (using your kubeconfig or in-cluster credentials) and exposes a simple HTTP surface for inspecting cluster state, streaming pod logs, and enumerating events — useful for ad-hoc debugging, integration with external tools, or as a development-time service inside clusters.

The server is intentionally minimal and extensible: it focuses on the common needs of exploring workloads and troubleshooting (pods, namespaces, events, logs) while providing a straightforward extension surface so teams can add custom endpoints or integrate it into larger observability workflows.

Features

• Browse Kubernetes namespaces and pods via HTTP
• Stream or fetch pod logs (per-container, per-pod)
• List cluster events for troubleshooting
• Support for kubeconfig (local) or in-cluster authentication
• Lightweight, single binary written in Go
• Extensible: add custom HTTP handlers or resource endpoints
• Health and readiness checks for orchestration

Installation / Configuration

Clone and build from source:

git clone https://github.com/strowk/mcp-k8s-go.git
cd mcp-k8s-go
go build ./cmd/mcp-server
# produces a binary, e.g. ./mcp-server

Run locally with a kubeconfig:

./mcp-server -kubeconfig="$HOME/.kube/config" -listen=":8080"

Example flags (typical):

• -kubeconfig: Path to kubeconfig (optional when running in-cluster)
• -listen: Address and port to bind (default :8080)
• -tls-cert / -tls-key: Paths to TLS certificate and key (optional)
• -log-level: Logging verbosity

Run as Docker container (mount kubeconfig):

# Dockerfile (basic)
FROM golang:1.20 AS build
WORKDIR /src
COPY . .
RUN go build -o /bin/mcp-server ./cmd/mcp-server

FROM alpine:3.18
COPY --from=build /bin/mcp-server /usr/local/bin/mcp-server
ENTRYPOINT ["/usr/local/bin/mcp-server"]

Run image, mounting kubeconfig:

docker build -t mcp-k8s-go:latest .
docker run -p 8080:8080 -v ~/.kube/config:/root/.kube/config:ro mcp-k8s-go:latest \
  /usr/local/bin/mcp-server -kubeconfig=/root/.kube/config -listen=:8080

Kubernetes deployment hint: run in-cluster with a ServiceAccount that has read access to pods, namespaces and events.

Available Resources

Below are common HTTP endpoints exposed by the server (paths are examples; check the binary or docs for exact routes):

Example: fetch pods in the default namespace

curl "http://localhost:8080/api/v1/pods?namespace=default" | jq .

Stream logs (follow) from a container:

curl -N "http://localhost:8080/api/v1/pods/default/my-pod/logs?container=web&follow=true"

Extending the Server

The project is designed to be extended in Go. Typical extension points:

• Add new HTTP handlers that call the Kubernetes clientset
• Add middleware for authentication / RBAC
• Add endpoints that aggregate or transform k8s objects for UI clients

Minimal example adding a new route (illustrative):

http.HandleFunc("/api/v1/custom", func(w http.ResponseWriter, r *http.Request) {
    // use clientset to query k8s and write JSON
    items, _ := client.CoreV1().Pods("default").List(ctx, metav1.ListOptions{})
    json.NewEncoder(w).Encode(items)
})

Use Cases

• Debugging pod failures: quickly fetch pod lists, recent events and pod logs without running kubectl; useful in constrained environments or CI containers.
• Developer tooling: embed the MCP server as a helper sidecar that exposes simplified debugging endpoints to developer UIs or web consoles.
• Automation and scripts: call the HTTP endpoints from CI jobs or scripts to collect diagnostics for flaky tests (collect logs + events).
• Learning and inspections: use the server in a sandbox cluster to teach Kubernetes object relationships, logs and events with a simple HTTP client.

Concrete example — fetch recent events and pod logs for troubleshooting:

1. List pods in namespace “staging”: curl “http://localhost:8080/api/v1/pods?namespace=staging”
2. Get events for the same namespace: curl “http://localhost:8080/api/v1/events?namespace=staging”
3. Stream the failing pod’s logs: curl -N “http://localhost:8080/api/v1/pods/staging/web-123/logs?container=web&follow=true”

Helpful Tips

• Ensure the ServiceAccount used in-cluster has read permissions for pods, namespaces and events.
• Use labelSelector query parameters (if supported) to filter large clusters.
• Combine with simple UIs or proxy tooling (e.g., port-forwarding, ingress) for secure remote access.

Repository and source code: https://github.com/strowk/mcp-k8s-go