k8s-diagnostics

Kubernetes Diagnostics MCP Server provides a suite of intelligent troubleshooting tools tailored for Kubernetes clusters. It exposes capabilities to diagnose pod issues, assess cluster health, obtain workload recommendations, and analyze pod logs to surface error patterns and contextual suggestions. Use the available tools to quickly pinpoint root causes during incidents, obtain actionable remediation steps, and guide platform teams toward best practices for deployments and service configurations.

To use the server, query the following tools:

• diagnose_pod: Inspect a specific pod for health, restart counts, ready status, recent events, and resource configuration. Pass pod_name and optional namespace to target the pod.
• analyze_cluster_health: Retrieve an overview of nodes, namespaces, problematic pods, resource usage, and cluster-wide recommendations.
• get_workload_recommendations: Get best-practice recommendations for deployments (resource limits, replica counts, affinities, etc.) within a namespace.
• analyze_pod_logs: Retrieve and analyze logs from a pod (with optional container and number of lines) to detect error patterns and provide contextual suggestions.

These tools are designed to work with in-cluster or external clusters using either kubeconfig or in-cluster authentication, and they return structured data that can be consumed by automation workflows or integrated into chat-based incident response processes.

Prerequisites:

• Go 1.21+ installed on your machine
• Access to a Kubernetes cluster (in-cluster or with kubeconfig)
• kubectl configured or running inside a Kubernetes cluster

Installation steps:

1. Clone the repository and navigate into it

git clone <this-repo>
cd k8s-diagnostics-mcp

2. Resolve dependencies and build the binary

go mod tidy
go build -o k8s-diagnostics-mcp

3. Run the MCP server locally (example)

./k8s-diagnostics-mcp

Notes:

• The server automatically detects Kubernetes configuration, using in-cluster service accounts when running inside Kubernetes, or ~/.kube/config / KUBECONFIG when running locally.

Environment and configuration tips:

• In-cluster mode will use the Kubernetes service account automatically. Ensure the deployment has appropriate RBAC permissions for diagnostics actions.
• Local development can rely on ~/.kube/config or KUBECONFIG for cluster access.
• If you encounter connection or authorization errors, verify that your kubeconfig context points to the right cluster and that your client has sufficient permissions to list pods, nodes, and deployments.
• The tools return structured data; you can wire them into dashboards or chat-based workflows for proactive incident response.
• For production deployments, consider running the MCP server as a Kubernetes Deployment and expose it via a service or API gateway, ensuring appropriate authentication and rate limiting.