This server provides read-only Kubernetes diagnostics through MCP tools.
List all namespaces in the cluster
List pods in a namespace with lifecycle phase and IP, optionally filtered by label selector
Retrieve pod logs with configurable tail lines and container selection
List cluster events, with optional namespace scope and warning-only filtering
List deployments with desired vs. available replica counts
List services with type and exposed ports
All operations are strictly read-only and avoid exposing secrets or config maps
Provides read-only tools for inspecting and diagnosing Kubernetes clusters, including listing pods and retrieving pod logs.
Production-ready Kubernetes diagnostics and cluster observability MCP server for AI agents.
k8s-mcp-server is a Model Context Protocol (MCP) server providing automated, read-only diagnostic tools for inspecting Kubernetes clusters. It allows AI agents to troubleshoot pod crashes, inspect ingress routes, and analyze cluster-wide warning events safely.
Related MCP server: Kubernetes Tools MCP Server
Tool | Category | Description |
| Infrastructure | Lists nodes, readiness states, roles, and kubelet versions. |
| Workloads | Detects abnormal pod phases, restart loops, and CrashLoopBackOffs. |
| Observability | Retrieves container stdout/stderr logs with tail limits and crash inspection. |
| Diagnostics | Aggregates FailedScheduling, FailedMount, and BackOff warning events. |
| Networking | Audits HTTP routing rules, host headers, and TLS certificates. |
Python 3.11+
Active Kubernetes cluster access (~/.kube/config or in-cluster ServiceAccount)
Read-only RBAC privileges (get, list on core and networking API groups)
git clone https://github.com/akkireddy-challa/k8s-mcp-server.git
cd k8s-mcp-server
pip install -r requirements.txt
python server.pyAdd to claude_desktop_config.json:
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["/path/to/k8s-mcp-server/server.py"],
"env": {
"KUBECONFIG": "/Users/<username>/.kube/config"
}
}
}
}Strictly Read-Only: Enforces GET and LIST operations only.
Zero-Secret Exposure: Secrets and config maps are never inspected or surfaced to LLM context.
Flexible Auth: Supports standard ~/.kube/config context or in-cluster pod ServiceAccounts.
MIT License. See LICENSE for details.
Built by Akkireddy Challa — Platform Engineer at Telia, Stockholm.
Retrieve Kubernetes cluster events to diagnose scheduling failures, node pressure, or eviction warnings.
Call this tool when pods remain stuck in 'Pending' or 'CrashLoopBackOff' states.
Use warning_only=True to eliminate normal informational noise during triage.
Read-only query.
Returns up to the 50 most recent events formatted with event type, target resource, reason, and message.
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Namespace to query for events. Pass a specific namespace or 'all' to inspect entire cluster. | default |
| warning_only | No | When true, filters only Warning events (e.g. BackOff, FailedScheduling, Unhealthy). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explicitly declares it is a read-only query and describes the return format (up to 50 events, including type, target, reason, message). Since no annotations are provided, this full disclosure is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured into purpose, usage, and behavior sections. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two optional parameters, the description is complete. It provides the resource, purpose, output format, and usage conditions, which is sufficient for an agent to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions already fully cover both parameters (namespace and warning_only) with clear explanations. The tool description adds no additional semantic meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool retrieves Kubernetes cluster events for diagnosing scheduling failures, node pressure, or eviction warnings. This distinguishes it from sibling tools like list_pods or get_pod_logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit guidance: call this tool when pods are stuck in 'Pending' or 'CrashLoopBackOff' states. It also suggests using warning_only to filter noise, providing practical usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract stdout and stderr log streams from a pod container for diagnostics.
Use when investigating application crashes, HTTP 500 errors, or startup exceptions.
Keep tail_lines small (e.g. 50–200) to avoid overloading LLM token context.
Read-only query.
Returns raw text log lines or a descriptive error if the pod or container does not exist.
| Name | Required | Description | Default |
|---|---|---|---|
| pod_name | Yes | Exact identifier name of the pod whose logs should be extracted (e.g. 'nginx-7854ff8877-abcde'). | |
| container | No | Specific container name within a multi-container pod. If omitted, Kubernetes selects the primary container. | |
| namespace | No | Kubernetes namespace where the target pod resides. Defaults to 'default'. | default |
| tail_lines | No | Number of most recent log lines to fetch. Constrained between 1 and 2000. Defaults to 100. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: it is a read-only query, returns raw text log lines, and gives a descriptive error for nonexistent pods or containers. It also explains the default container selection behavior when omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with clear sections for usage guidelines and behavioral transparency. Every sentence contributes useful information without redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides sufficient context for correct usage: when to use, parameter defaults and constraints, behavior details, and error semantics. It is fully self-contained for an agent to invoke the tool appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds meaningful context beyond the schema, such as the primary container selection when container is omitted, namespace defaulting, and the bounded range of tail_lines. This enriches the parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool extracts stdout and stderr log streams from a pod container for diagnostics, with a specific verb and resource. Distinct from sibling tools that list resources or events, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use the tool (investigating crashes, HTTP 500 errors, startup exceptions) and offers practical guidance to keep tail_lines small to avoid token overload. This leaves no ambiguity about appropriate invocation contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List deployments in a namespace with desired vs available replica counts.
Use this tool to verify rollout status and check whether workloads meet desired scale.
When replicas show 0 available, use list_pods and get_cluster_events to locate the failure.
Read-only operation using AppsV1Api.
Returns name, desired replicas, and ready replica count.
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Target Kubernetes namespace to list deployments from. Defaults to 'default'. | default |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that the operation is read-only and uses AppsV1Api, disclosing the primary behavioral trait. Since no annotations are provided, the description carries the full burden, and while it could mention error handling or edge cases, the read-only nature is clearly communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the main purpose stated in a single sentence. It is front-loaded with the primary function, and the additional sections are clearly separated and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, usage, behavioral transparency, and even provides guidance on related tools when issues arise. For a simple read-only list operation, it provides all necessary context without requiring the agent to infer functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a full description for the namespace parameter, achieving 100% coverage. The tool description does not add any extra semantics beyond what is in the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: listing deployments with desired vs available replica counts. It specifies the resource type and the key information returned, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage guidelines explicitly state when to use this tool (verify rollout status, check desired scale) and when to use alternatives (use list_pods and get_cluster_events when replicas are 0 available). This provides clear decision-making guidance for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all namespaces present in the connected Kubernetes cluster.
Call this tool first when discovering available cluster domains or when the user does not supply an explicit namespace.
Do not use this tool to inspect workload health; use list_pods instead.
Read-only operation.
Scans cluster-wide namespace resources using CoreV1Api.
Returns an alphabetically sorted list of namespace names with total count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Explicitly states the operation is read-only and describes what it does (scans CoreV1Api) and what it returns (sorted names with count). No side effects or hidden behaviors are implied, and with no annotations, the description fully covers safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using short sentences and clear structure. Every line adds value, including the return format and usage guidance, with no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the essential context needed to invoke the tool: what it does, when to use it, what it returns, and how it differs from a sibling tool. No missing information for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there are no parameter semantics to clarify. The description's lack of parameter detail is appropriate and complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool lists all namespaces in the connected Kubernetes cluster, with a specific verb and resource scope. The scope is unambiguous and directly matches the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (first when discovering cluster domains or no explicit namespace) and when not to use (for workload health, use list_pods). This gives the agent clear decision-making criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List pods within a specified namespace along with their lifecycle phase and IP address.
Use this tool when identifying running workloads, crash loops, or verifying pod readiness.
If troubleshooting a failing pod, pass its name to get_pod_logs or call get_cluster_events.
Read-only operation.
Omits internal container state arrays; highlights high-level phase (Running, Pending, Failed).
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Target Kubernetes namespace (e.g. 'kube-system', 'production', or 'default'). | default |
| label_selector | No | Kubernetes label query expression to filter pods (e.g. 'app=frontend' or 'tier=backend'). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although no annotations are provided, the description explicitly discloses the tool's read-only nature and its behavior of omitting internal container state arrays while highlighting high-level phases. This gives the agent important transparency about side effects and data scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with the primary purpose stated in the first sentence. The additional usage and transparency sections are brief and directly relevant, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to explain return values. The description, usage guidelines, and transparency notes together provide sufficient context for an agent to decide when and how to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full descriptions for both parameters (namespace and label_selector), including examples, so coverage is 100%. The description does not add significant extra semantic detail beyond the schema, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('List pods'), the target resource ('pods'), and the scope ('within a specified namespace'), along with the key returned attributes ('lifecycle phase and IP address'). This distinguishes it from sibling tools like get_pod_logs and list_namespaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage guidelines explicitly state when to use the tool ('identifying running workloads, crash loops, or verifying pod readiness') and when to use alternatives ('If troubleshooting a failing pod, pass its name to get_pod_logs or call get_cluster_events'). This provides clear decision guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Kubernetes services, exposed ports, and service types within a namespace.
Use this tool when checking network ingress, internal DNS resolution, or service endpoints.
Complement with list_pods to confirm underlying backend endpoints exist.
Read-only query using CoreV1Api.
Lists service name, type (ClusterIP, NodePort, LoadBalancer), and mapped ports.
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Target Kubernetes namespace to inspect services in. Defaults to 'default'. | default |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are not provided, so the description carries the full burden of disclosing behavioral traits. It explicitly states 'Read-only query using CoreV1Api', making the read-only nature transparent. This goes beyond a generic action and is valuable for users.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet structured with clear sections for overview, usage, and behavior. It avoids redundancy and fluff, with every sentence adding value. The structure aligns with the provided template, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation, the description is complete: it states what it lists, gives usage context, and clarifies read-only behavior. The output schema is not detailed, but the description mentions the fields returned (service name, type, ports). No missing context is apparent for a typical use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides a full description for the single parameter 'namespace' (including default), yielding 100% schema coverage. The tool description does not add extra meaning beyond the schema; it repeats the same information. Per the rubric, high coverage sets baseline at 3, and no additional insight is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('Kubernetes services'), and the scope ('within a namespace'). It also specifies the details returned (exposed ports, service types), making the purpose unambiguous. Sibling tools are listed, and the usage guidelines further differentiate it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides when to use the tool ('checking network ingress, internal DNS resolution, or service endpoints') and recommends complementing with list_pods. This gives clear guidance relative to alternatives, fulfilling the usage guideline criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_cluster_eventsget_pod_logslist_deploymentslist_namespaceslist_podslist_servicesScored across 6 tools
Each tool targets a distinct Kubernetes resource or action: namespaces, pods, logs, events, deployments, and services. No functional overlap that would confuse tool selection.
Names follow a consistent lowercase snake_case verb_noun pattern, but four use 'list_' while two use 'get_'. The split is semantically reasonable yet not perfectly uniform.
Six tools form a focused, readable set for read-only Kubernetes inspection and troubleshooting, without redundant or excessive entries.
The set covers the core resources needed for workload troubleshooting: namespaces, pods, logs, cluster events, deployments, and services. There are no obvious dead ends for the inferred read-only diagnostic domain.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
The Google GKE MCP server is a managed Model Context Protocol server that provides AI applications with tools to manage Google Kubernetes Engine (GKE) clusters and Kubernetes resources. It exposes a structured, discoverable interface that allows AI agents to interact with GKE and Kubernetes APIs, enabling them to inspect cluster configurations, retrieve Kubernetes resource YAMLs, monitor operations like cluster upgrades, diagnose issues, and optimize costs—all without needing to parse text output or use complex kubectl commands.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/akkireddy-challa/k8s-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server