poly-k8s-mcp

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

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

• Deno runtime (v2.0+)

• kubectl CLI

• Helm CLI (optional, for Helm tools)

• Kustomize CLI (optional, for Kustomize tools)

• Valid kubeconfig (~/.kube/config or KUBECONFIG env var)

Installation

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

Usage

Run as MCP server (Local-Agent mode):

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

Or use the systemd service:

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

Smoke Test

Verify the server is working correctly:

# 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