Kubernetes

You interact with Kubernetes clusters through a standardized MCP interface that lets you discover API resources, list and inspect objects, fetch logs and metrics, and perform controlled changes. This MCP server provides a consistent way to drive Kubernetes tooling from CLI, web, or IDE integrations, while offering secure, mode-based operation and flexible authentication options.

How to use

To use the Kubernetes MCP Server, connect an MCP client to its endpoints using either the standard HTTP MCP transport or the local stdio interface for CLI integrations. In HTTP mode, you make JSON-RPC requests to the server’s HTTP endpoints and receive structured responses. In stdio mode, you communicate through standard input and output with the same command set exposed by the MCP server.

You can perform a wide range of operations, including discovering available Kubernetes API resources, listing and inspecting resources, retrieving pod logs and node/pod metrics, getting events, creating or updating resources from manifests, rolling out restarts, and managing Helm releases. The server can operate in read-only mode to safely explore your cluster, or you can enable write operations as needed.

How to install

Prerequisites you need before running the MCP server:

• Go 1.23 or later

• Access to a Kubernetes cluster and a configured kubeconfig or API credentials

Step-by-step setup to run the MCP server locally in SSE mode (the default web-facing mode):

# 1. Build from source
GO111MODULE=on
export GOPATH=$(go env GOPATH)

git clone https://github.com/reza-gholizade/k8s-mcp-server.git
cd k8s-mcp-server

go mod download

# 2. Build the server binary
go build -o k8s-mcp-server main.go

# 3. Start in SSE mode (default port 8080)
./k8s-mcp-server --mode sse

Additional configuration and usage notes

The server supports multiple authentication methods. It can use kubeconfig content from an environment variable, API server URL plus a token, or in-cluster service account credentials when running inside a Kubernetes cluster. You can also run with a kubeconfig file path. The server exposes three modes for clients: stdio for CLI tooling, sse for web applications, and streamable-http for web integrations.

Security and deployment considerations

Run the MCP server as a non-root user inside containers for enhanced security. The server provides health checks and supports read-only mode to safely observe cluster state without making changes. When using the Docker image, mount kubeconfig read-only to the non-root user home directory or provide credentials through environment variables.

Using the Docker Image

You can run the MCP server from the official Docker image. Use the default SSE mode to serve requests from a web client, or switch to streamable-http or stdio as needed.

Examples show mounting your kubeconfig into the container or providing authentication via environment variables.

Notes about available operations

This server provides a comprehensive set of tools to work with Kubernetes resources, including creation, updates, deletions, resource descriptions, and access to metrics and events. You can enable read-only mode to safeguard your cluster while you explore capabilities.

Troubleshooting

If the server cannot connect to Kubernetes, verify your kubeconfig or API credentials, ensure the correct context is used, and confirm network access to the API server. If run in a container, ensure the kubeconfig path is mounted correctly and that the container user has the appropriate permissions.

Available tools

getAPIResources

Retrieves all available API resources in the Kubernetes cluster.

listResources

Lists all instances of a specific resource type with optional namespace and label filtering.

getResource

Retrieves detailed information about a specific resource.

describeResource

Provides a comprehensive description of a resource similar to kubectl describe.

getPodsLogs

Fetches logs from a specific pod, with optional container targeting.

getNodeMetrics

Retrieves resource usage metrics for a specific node.

getPodMetrics

Retrieves CPU and memory metrics for a specific pod.

getEvents

Lists events for a namespace or a specific resource.

createOrUpdateResource

Creates or updates a resource from a JSON manifest.

createOrUpdateResourceYAML

Creates or updates a resource from a YAML manifest with improved YAML handling.

rolloutRestart

Triggers a rolling restart for resources that support template edits.

deleteResource

Deletes a specified resource from the cluster.

getIngresses

Retrieves ingress resources, optionally filtered by host.

helmInstall

Installs a Helm chart into the cluster.

helmUpgrade

Upgrades an existing Helm release.

helmList

Lists Helm releases in the cluster or a specific namespace.

helmGet

Gets details of a specific Helm release.

helmHistory

Retrieves the history of a Helm release.

helmRollback

Rolls back a Helm release to a previous revision.

helmUninstall

Uninstalls a Helm release from the cluster.

helmRepoList

Lists Helm repositories configured for use with Helm charts.

helmRepoAdd

Adds a Helm repository for chart retrieval.