= poly-k8s-mcp

image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] image:https://img.shields.io/badge/Philosophy-Palimpsest-purple.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-licence"]

:toc: :toc-placement!:

image:https://img.shields.io/badge/RSR-compliant-gold[RSR Compliant,link=https://github.com/hyperpolymath/rhodium-standard-repositories] image:https://img.shields.io/badge/MCP-server-blue[MCP Server,link=https://github.com/modelcontextprotocol]

Unified MCP server for Kubernetes orchestration. Provides Model Context Protocol tools for managing Kubernetes clusters through kubectl, Helm, and Kustomize.

toc::[]

== Overview

poly-k8s-mcp exposes Kubernetes management capabilities through the Model Context Protocol (MCP), enabling AI assistants and other MCP clients to interact with Kubernetes clusters programmatically.

== Adapters

=== kubectl (12 tools) Core Kubernetes CLI operations:

• kubectl_get - Get resources (pods, deployments, services, etc.)
• kubectl_describe - Show detailed resource information
• kubectl_logs - View container logs
• kubectl_apply - Apply manifests
• kubectl_delete - Delete resources
• kubectl_exec - Execute commands in containers
• kubectl_scale - Scale deployments/replicasets
• kubectl_rollout - Manage rollouts (status, history, undo, restart)
• kubectl_port_forward - Forward ports (returns command to run)
• kubectl_context - Manage kubectl contexts
• kubectl_top - Show resource usage (CPU/memory)
• kubectl_create - Create resources

=== Helm (14 tools) Kubernetes package manager:

• helm_install - Install charts
• helm_upgrade - Upgrade releases
• helm_uninstall - Uninstall releases
• helm_list - List releases
• helm_status - Get release status
• helm_history - View release history
• helm_rollback - Rollback to previous revision
• helm_repo_add - Add chart repositories
• helm_repo_list - List repositories
• helm_repo_update - Update repository cache
• helm_search - Search for charts
• helm_show - Show chart information
• helm_template - Render templates locally
• helm_get - Get release information

=== Kustomize (8 tools) Kubernetes configuration management:

• kustomize_build - Build kustomization into manifests
• kustomize_apply - Build and apply to cluster
• kustomize_create - Create kustomization.yaml
• kustomize_edit_add - Add resources/patches/configmaps
• kustomize_edit_set - Set namespace/nameprefix/image
• kustomize_edit_remove - Remove items
• kustomize_cfg - Run cfg commands (cat, count, grep, tree)
• kustomize_version - Show version

== Runtime Mode

[IMPORTANT]

Local-Agent Mode Only — This MCP server wraps CLI tools (kubectl, helm, kustomize) and requires --allow-run permission. It cannot run in Hosted-HTTP mode.

|=== |Mode |Supported |Notes

|Local-Agent (stdio) |✓ Yes |Primary mode. Runs locally, executes CLI commands.

|Hosted-HTTP |✗ No |Cannot wrap CLI tools from a hosted environment. |===

== Security Boundary

[WARNING]

This MCP server executes external CLI commands using Deno's --allow-run permission. The security boundary is your local kubectl/helm/kustomize configuration.

What this means:

• Commands run with your current kubeconfig and credentials
• The MCP client (e.g., Claude) can perform any kubectl/helm/kustomize action you can
• Cluster access is determined by your local ~/.kube/config
• No additional authentication layer between MCP and the CLIs

Recommendations:

1. Use a restricted kubeconfig for MCP access if possible
2. Consider namespace-scoped RBAC roles
3. Avoid running this MCP server with cluster-admin credentials
4. Review tool calls before approving in your MCP client

== Requirements

• https://deno.land/[Deno] runtime (v2.0+)
• https://kubernetes.io/docs/reference/kubectl/[kubectl] CLI
• https://helm.sh/[Helm] CLI (optional, for Helm tools)
• https://kustomize.io/[Kustomize] CLI (optional, for Kustomize tools)
• Valid kubeconfig (~/.kube/config or KUBECONFIG env var)

== Installation

[source,bash]

git clone https://github.com/hyperpolymath/poly-k8s-mcp cd poly-k8s-mcp

== Usage

Run as MCP server (Local-Agent mode):

[source,bash]

deno run --allow-run --allow-read --allow-env --allow-write main.js

Or use the systemd service:

[source,bash]

systemctl --user enable poly-k8s-mcp systemctl --user start poly-k8s-mcp

== Smoke Test

Verify the server is working correctly:

[source,bash]

1. Check Deno can run the server

deno run --allow-run --allow-read --allow-env --allow-write main.js & SERVER_PID=$!

2. Verify kubectl is accessible

kubectl version --client

3. Test basic tool (requires cluster access)

The MCP client should be able to call kubectl_get

4. Cleanup

kill $SERVER_PID

Expected smoke test results:

|=== |Check |Expected Result

|Server starts |No errors, listens on stdio

|kubectl available |kubectl version --client returns version

|kubectl_get works |Returns pod list (if cluster accessible)

|Helm available (optional) |helm version returns version

|Kustomize available (optional) |kustomize version returns version |===

== License

MIT