/ 
MCP-K8s-0.002
/ mcp-k8s

NAME

mcp-k8s - MCP Server for Kubernetes with RBAC-aware dynamic tools

VERSION

version 0.002

SYNOPSIS

# Start with default kubeconfig and context:
$ mcp-k8s

# Specify a context:
$ MCP_K8S_CONTEXT=my-cluster mcp-k8s

# Restrict to specific namespaces:
$ MCP_K8S_NAMESPACES=default,staging mcp-k8s

# Direct token authentication:
$ MCP_K8S_TOKEN="eyJhbGci..." MCP_K8S_SERVER=https://my-cluster:6443 mcp-k8s

# Full example:
$ KUBECONFIG=/path/to/config MCP_K8S_CONTEXT=prod MCP_K8S_NAMESPACES=app mcp-k8s

DESCRIPTION

mcp-k8s starts an MCP (Model Context Protocol) server on stdio that gives AI assistants access to a Kubernetes cluster. It uses the current kubeconfig to connect and dynamically discovers RBAC permissions to determine which tools to expose.

This is the entry point for integrating Kubernetes with Claude Desktop, Claude Code, or any MCP-compatible AI assistant.

CONFIGURATION

The server is configured entirely through environment variables — no command-line flags needed. This makes it easy to configure in MCP client settings (JSON).

Environment Variables

KUBECONFIG

Path to kubeconfig file. Defaults to ~/.kube/config.

MCP_K8S_CONTEXT

Which kubeconfig context to use. Defaults to the kubeconfig's current-context.

MCP_K8S_TOKEN

Bearer token for direct authentication. Bypasses kubeconfig entirely.

MCP_K8S_SERVER

Kubernetes API server URL. Used with MCP_K8S_TOKEN or in-cluster auth. Defaults to https://kubernetes.default.svc.cluster.local when in-cluster.

MCP_K8S_NAMESPACES

Comma-separated list of namespaces. Defaults to auto-discovery (all namespaces the service account can list).

CLAUDE DESKTOP

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-k8s",
      "env": {
        "MCP_K8S_CONTEXT": "my-cluster",
        "MCP_K8S_NAMESPACES": "default,production"
      }
    }
  }
}

CLAUDE CODE

Add to your project's .mcp.json:

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-k8s",
      "env": {
        "MCP_K8S_CONTEXT": "dev-cluster"
      }
    }
  }
}

TOOLS PROVIDED

The server registers 10 MCP tools, each gated by RBAC permissions:

k8s_permissions — Show what the service account can do
k8s_list — List resources (Pods, Deployments, Services, ...)
k8s_get — Get a single resource (summary, JSON, or YAML)
k8s_create — Create a resource from a manifest
k8s_patch — Partially update a resource
k8s_delete — Delete a resource
k8s_logs — Get pod container logs
k8s_events — Get events for debugging
k8s_rollout_restart — Trigger rolling restart of Deployment/StatefulSet/DaemonSet
k8s_apply — Create or update a resource (like kubectl apply)

SEE ALSO

MCP::K8s — The module that powers this script

Kubernetes::REST::Kubeconfig — How kubeconfig is parsed

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-mcp-k8s/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.