Kubernetes MCP Server

✨ Features | 🚀 Getting Started | 🎥 Demos | ⚙️ Configuration | 🛠️ Tools | 💬 Community | 🧑‍💻 Development

https://github.com/user-attachments/assets/be2b67b3-fc1c-4d11-ae46-93deba8ed98e

✨ Features

A powerful and flexible Kubernetes Model Context Protocol (MCP) server implementation with support for Kubernetes and OpenShift.

• ✅ Configuration:
  • Automatically detect changes in the Kubernetes configuration and update the MCP server.
  • View and manage the current Kubernetes .kube/config or in-cluster configuration.
• ✅ Generic Kubernetes Resources: Perform operations on any Kubernetes or OpenShift resource.
  • Any CRUD operation (Create or Update, Get, List, Delete).
• ✅ Pods: Perform Pod-specific operations.
  • List pods in all namespaces or in a specific namespace.
  • Get a pod by name from the specified namespace.
  • Delete a pod by name from the specified namespace.
  • Show logs for a pod by name from the specified namespace.
  • Top gets resource usage metrics for all pods or a specific pod in the specified namespace.
  • Exec into a pod and run a command.
  • Run a container image in a pod and optionally expose it.
• ✅ Namespaces: List Kubernetes Namespaces.
• ✅ Events: View Kubernetes events in all namespaces or in a specific namespace.
• ✅ Projects: List OpenShift Projects.
• ☸️ Helm:
  • Install a Helm chart in the current or provided namespace.
  • List Helm releases in all namespaces or in a specific namespace.
  • Uninstall a Helm release in the current or provided namespace.
• 🔧 Tekton: Tekton-specific operations that complement generic Kubernetes resource management.
  • Pipeline: Start a Tekton Pipeline by creating a PipelineRun.
  • PipelineRun: Restart, cancel, troubleshoot, and retrieve PipelineRun logs.
  • Task: Start a Tekton Task by creating a TaskRun.
  • TaskRun: Restart a TaskRun with the same spec, and retrieve TaskRun logs via pod resolution.
• 🔭 Observability: Optional OpenTelemetry distributed tracing and metrics with custom sampling rates. Includes /stats endpoint for real-time statistics. See OTEL.md.

Unlike other Kubernetes MCP server implementations, this IS NOT just a wrapper around kubectl or helm command-line tools. It is a Go-based native implementation that interacts directly with the Kubernetes API server.

There is NO NEED for external dependencies or tools to be installed on the system. If you’re using the native binaries you don’t need to have Node or Python installed on your system.

• ✅ Lightweight: The server is distributed as a single native binary for Linux, macOS, and Windows.
• ✅ High-Performance / Low-Latency: Directly interacts with the Kubernetes API server without the overhead of calling and waiting for external commands.
• ✅ Multi-Cluster: Can interact with multiple Kubernetes clusters simultaneously (as defined in your kubeconfig files).
• ✅ Cross-Platform: Available as a native binary for Linux, macOS, and Windows, as well as an npm package, a Python package, and container/Docker image.
• ✅ Configurable: Supports command-line arguments, TOML configuration files, and environment variables.
• ✅ Well tested: The server has an extensive test suite to ensure its reliability and correctness across different Kubernetes environments.
• 📚 Documentation: Comprehensive user documentation including setup guides, configuration reference, and observability.

🚀 Getting Started

Requirements

• Access to a Kubernetes cluster.

Claude Desktop

Using npx

If you have npm installed, this is the fastest way to get started with kubernetes-mcp-server on Claude Desktop.

Open your claude_desktop_config.json and add the mcp server to the list of mcpServers:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubernetes-mcp-server@latest"]
    }
  }
}

VS Code / VS Code Insiders

Install the Kubernetes MCP server extension in VS Code Insiders by pressing the following link:

Alternatively, you can install the extension manually by running the following command:

# For VS Code
code --add-mcp '{"name":"kubernetes","command":"npx","args":["kubernetes-mcp-server@latest"]}'
# For VS Code Insiders
code-insiders --add-mcp '{"name":"kubernetes","command":"npx","args":["kubernetes-mcp-server@latest"]}'

Cursor

Install the Kubernetes MCP server extension in Cursor by pressing the following link:

Alternatively, you can install the extension manually by editing the mcp.json file:

{
  "mcpServers": {
    "kubernetes-mcp-server": {
      "command": "npx",
      "args": ["-y", "kubernetes-mcp-server@latest"]
    }
  }
}

Goose CLI

Goose CLI is the easiest (and cheapest) way to get rolling with artificial intelligence (AI) agents.

Using npm

If you have npm installed, this is the fastest way to get started with kubernetes-mcp-server.

Open your goose config.yaml and add the mcp server to the list of mcpServers:

extensions:
  kubernetes:
    command: npx
    args:
      - -y
      - kubernetes-mcp-server@latest

🎥 Demos

Diagnosing and automatically fixing an OpenShift Deployment

Demo showcasing how Kubernetes MCP server is leveraged by Claude Desktop to automatically diagnose and fix a deployment in OpenShift without any user assistance.

https://github.com/user-attachments/assets/a576176d-a142-4c19-b9aa-a83dc4b8d941

Vibe Coding a simple game and deploying it to OpenShift

In this demo, I walk you through the process of Vibe Coding a simple game using VS Code and how to leverage Podman MCP server and Kubernetes MCP server to deploy it to OpenShift.

Supercharge GitHub Copilot with Kubernetes MCP Server in VS Code - One-Click Setup!

In this demo, I’ll show you how to set up Kubernetes MCP server in VS code just by clicking a link.

⚙️ Configuration

The Kubernetes MCP server can be configured using command line (CLI) arguments.

You can run the CLI executable either by using npx, uvx, or by downloading the latest release binary.

# Run the Kubernetes MCP server using npx (in case you have npm and node installed)
npx kubernetes-mcp-server@latest --help

# Run the Kubernetes MCP server using uvx (in case you have uv and python installed)
uvx kubernetes-mcp-server@latest --help

# Run the Kubernetes MCP server using the latest release binary
./kubernetes-mcp-server --help

Configuration Options

Note: Runtime settings are TOML (or existing env names), not CLI flags. See Configuration Changes for the flag-to-TOML mapping.

TOML Configuration Files

For complex or persistent configurations, use TOML configuration files instead of CLI arguments:

kubernetes-mcp-server --config /etc/kubernetes-mcp-server/config.toml

Example configuration:

log_level = 2
read_only = true
toolsets = ["core", "config", "helm", "kubevirt"]

# Deny access to sensitive resources
[[denied_resources]]
group = ""
version = "v1"
kind = "Secret"

[telemetry]
endpoint = "http://localhost:4317"

For comprehensive TOML configuration documentation, including:

• All configuration options and their defaults
• Drop-in configuration files for modular settings
• Dynamic configuration reload via SIGHUP
• Denied resources for restricting access to sensitive resource types
• Server instructions for MCP Tool Search
• Custom MCP prompts
• OAuth/OIDC authentication for HTTP mode (Keycloak, Microsoft Entra ID)

See the Configuration Reference.

📊 MCP Logging

The server supports the MCP logging capability, allowing clients to receive debugging information via structured log messages. Kubernetes API errors are automatically categorized and logged to clients with appropriate severity levels. Sensitive data (tokens, keys, passwords, cloud credentials) is automatically redacted before being sent to clients.

See the MCP Logging Guide.

🛠️ Tools and Functionalities

The Kubernetes MCP server supports enabling or disabling specific groups of tools and functionalities (tools, resources, prompts, and so on) via the toolsets configuration option. This allows you to control which Kubernetes functionalities are available to your AI tools. Enabling only the toolsets you need can help reduce the context size and improve the LLM’s tool selection accuracy.

Validated Kubernetes Ecosystem Projects

The following CNCF and Kubernetes ecosystem projects are covered by automated evaluation scenarios in evals/tasks. Most scenarios work with just the core toolset. The dedicated toolsets below are optional and only needed for the project-specific scenarios noted.

Available Toolsets

The following sets of tools are available (toolsets marked with ✓ in the Default column are enabled by default):

Tools

In case multi-cluster support is enabled (default) and you have access to multiple clusters, all applicable tools will include an additional context argument to specify the Kubernetes context (cluster) to use for that operation.

Some tools require additional cluster APIs, resource instances, or permissions. See Tool requirements for availability prerequisites.

Prompts

Resources

Resource Templates

Helm Chart

A Helm Chart is available to simplify the deployment of the Kubernetes MCP server.

helm install kubernetes-mcp-server oci://ghcr.io/containers/charts/kubernetes-mcp-server

For configuration options including OAuth, telemetry, and resource limits, see the chart README and values.yaml.

💬 Community

Join the conversation and connect with other users and contributors:

• Slack - Ask questions, share feedback, and discuss the Kubernetes MCP server in the #kubernetes-mcp-server channel on the CNCF Slack workspace. If you’re not already a member, you can request an invitation.

🧑‍💻 Development

Running with mcp-inspector

Compile the project and run the Kubernetes MCP server with mcp-inspector to inspect the MCP server.

# Compile the project
make build
# Run the Kubernetes MCP server with mcp-inspector
npx @modelcontextprotocol/inspector@latest $(pwd)/kubernetes-mcp-server

---

mcp-name: io.github.containers/kubernetes-mcp-server