Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/hyperpolymath/poly-k8s-mcp

Unified MCP server for Kubernetes orchestration. Tools for kubectl, Helm, and Kustomize.
https://github.com/hyperpolymath/poly-k8s-mcp

deno helm hyperpolymath kubectl kubernetes kustomize mcp mcp-server model-context-protocol poly-mcp rescript

Last synced: 2 months ago
JSON representation

Unified MCP server for Kubernetes orchestration. Tools for kubectl, Helm, and Kustomize.

Awesome Lists containing this project

README 

          
= 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