clusterport

clusterport

clusterport is a small MCP server and CLI for core Kubernetes work. It is a clean-room rebuild of a core subset — twelve tools — from the documented surface of the community Flux159 mcp-server-kubernetes: get, describe and fetch logs; apply and create; delete, scale and patch; rollout actions and context switching; plus kubectl explain and API-resource listing.

Everything runs through the host's real kubectl. Each call is built as an argument array and spawned directly — never a shell string — so resource names, namespaces and patches cannot be reinterpreted as shell syntax. Manifests are never written to temp files or shell redirects: kubectl_apply sends its manifest over stdin (kubectl apply -f -), and kubectl_create generates a minimal manifest spec from its parameters and creates it from stdin the same way (kubectl create -f -). The executor is injectable, which is how the test suite verifies the exact argument arrays and stdin payloads with a fake.

Deliberately omitted: port-forward long-lived sessions, exec-into-pod, the helm tools, install/uninstall addon operations, non-resource URL operations, watch/streaming, and node operations such as cordon, taint or drain.

The host needs a working kubectl and cluster credentials. When kubectl is absent, calls fail honestly with the underlying spawn error (ENOENT) instead of a fabricated result. The published container image bundles no kubectl binary: it expects a host executor and says so in its Dockerfile.

Install

npx @reneturcios/clusterport kubectl-get pods -n default
docker run -i ghcr.io/cloudcorprecords/clusterport

CLI

clusterport kubectl-get <resource_type> [name] [-n namespace] [-o format]
clusterport kubectl-describe <resource_type> <name> [-n namespace]
clusterport kubectl-logs <name> [-n namespace] [-c container]
clusterport kubectl-apply "<manifest yaml>" [-n namespace] [--dry-run]
clusterport kubectl-create <resource_type> <name> [--image img] [-n namespace]
clusterport kubectl-delete <resource_type> <name> [-n namespace]
clusterport kubectl-scale <resource_type> <name> <replicas> [-n namespace]
clusterport kubectl-patch <resource_type> <name> '<json patch>' [-n namespace]
clusterport kubectl-rollout <resource_type> <name> <action> [-n namespace]
clusterport kubectl-context <current|list|use> [name]
clusterport explain-resource <resource> [--api-version v]
clusterport list-api-resources [kind]
clusterport --version

Exit codes: 0 success, 1 kubectl error, 2 usage error.

MCP server

npx -y @reneturcios/clusterport mcp

{
  "mcpServers": {
    "clusterport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/clusterport", "mcp"]
    }
  }
}

Tools

Tool	Input	What it does
kubectl_get	resource_type (required), name, namespace, output_format	kubectl get -o json by default; JSON parsed.
kubectl_describe	resource_type, name (required), namespace	kubectl describe.
kubectl_logs	name (required), namespace, container	kubectl logs.
kubectl_apply	manifest (required), namespace, dry_run	kubectl apply -f -, manifest over stdin.
kubectl_create	resource_type, name (required), namespace, image	Generated spec created via kubectl create -f - over stdin.
kubectl_delete	resource_type, name (required), namespace	kubectl delete.
kubectl_scale	resource_type, name, replicas (required), namespace	kubectl scale --replicas=n.
kubectl_patch	resource_type, name, patch (required), namespace	kubectl patch -p.
kubectl_rollout	resource_type, name, action (required), namespace	kubectl rollout <action> <type>/<name>.
kubectl_context	operation (required: current, list, use), name	kubectl config current/get/use-context.
explain_resource	resource (required), api_version	kubectl explain.
list_api_resources	kind (optional)	kubectl api-resources, parsed, kind-filtered.

Executor failures — a missing kubectl binary, an unreachable cluster, a nonexistent resource — are reported as tool errors carrying the underlying message.

Development

npm install
npm run build
npm test
npm run dev

Tests run entirely on a fake executor: exact argument arrays, stdin manifest passing for apply/create, output parsing, and error propagation. No live cluster is touched.

License

MIT — see LICENSE.