mcp-kubernetes

What is mCP-kubernetes?

mcp-kubernetes is a Model Context Protocol (MCP) server that enables AI assistants to interact with Kubernetes clusters. It bridges AI tools (like Claude, Cursor, and GitHub Copilot) and Kubernetes by translating natural language requests into Kubernetes operations and returning results that AI tools can understand.

How to use MCP-kubernetes?

Install via Docker or locally (requires kubectl and optionally helm). Configure it as an MCP server in your AI client (e.g., Claude Desktop, Cursor) using the provided JSON configuration. The server exposes a single call_kubectl tool (by default) that accepts any kubectl command, or legacy specialized tools if USE_LEGACY_TOOLS=true is set. Commands are filtered by access level (readonly, readwrite, or admin) set via the --access-level argument.

Key features of MCP-kubernetes

• Single unified call_kubectl tool that reduces context consumption.
• Access levels (readonly, readwrite, admin) filter available operations.
• Optional legacy tools (e.g., kubectl_resources, kubectl_workloads).
• Supports additional tools: Helm, Cilium, and Hubble via --additional-tools.
• Runs over stdio, SSE, or streamable-http transports.
• Configurable timeout, namespace filtering, and OTLP telemetry.

Use cases of MCP-kubernetes

• Query cluster status, pod states, and deployments using natural language.
• Debug a failing pod by viewing logs or events.
• Scale a deployment or apply a configuration file.
• Check RBAC permissions with kubectl auth can-i.
• Switch kubectl contexts or list all available contexts.

FAQ from MCP-kubernetes

What transport mechanisms are supported?

Stdio (default), SSE, and streamable-http. The transport is set via the --transport flag. SSE and streamable-http also require --host and --port arguments.

What access levels are available and what do they do?

readonly (default) allows only read operations (get, describe, logs, etc.). readwrite allows create, delete, apply, etc. admin allows all operations including cordon, drain, and taint. Tools are filtered at registration time so AI assistants only see permitted operations.

What environment variables are required or optional?

KUBECONFIG – path to your kubeconfig file (used when running locally). USE_LEGACY_TOOLS – set to true to use multiple specialized kubectl tools instead of the unified call_kubectl tool (default is false).

How do I control which namespaces are accessible?

Use the --allow-namespaces command-line argument with a comma-separated list of namespaces. An empty list means all namespaces are allowed.

Can I extend the server with tools beyond kubectl?

Yes. Use the --additional-tools flag with a comma-separated list: helm, cilium, and/or hubble. These tools become available as separate MCP tools (call_helm, call_cilium, call_hubble).