mcp-openshift

mcp-openshift

A safe-by-default Model Context Protocol server for OpenShift / Kubernetes. It lets an agent explore and operate a cluster — projects, pods and logs, deployments and deploymentconfigs, routes, services, builds, imagestreams, and any resource by kind — and, in higher modes, scale workloads, restart deployments, apply manifests, and delete.

Connect with a token from the web console you already use, or your username/password against the cluster's local identity provider.

Part of the dockndevai MCP server suite — one governance model across all of them.

What it gives an agent

Starts read-only (see Safe by default); higher-capability tools are only registered when you raise the mode.

Tool	For	Needs mode
whoami	confirm the authenticated identity	read-only
list_projects	projects/namespaces you can see	read-only
list_resources	list any kind (± namespace, label selector)	read-only
get_resource	one resource with full spec/status	read-only
pod_logs	a pod's container logs	read-only
list_events	recent events in a namespace	read-only
scale	set replicas on a Deployment/DeploymentConfig	read-write
rollout_restart	restart a Deployment	read-write
apply_resource	create/update from a manifest (SSA)	read-write + OPENSHIFT_ALLOW_APPLY
delete_resource	delete a resource	admin + OPENSHIFT_ALLOW_DELETE

Install

npx -y @dockndevai/mcp-openshift

You need your cluster's API URL and a credential. The quickest, since you use the browser console:

In the OpenShift web console, click your username (top-right) → Copy login command → Display Token. Copy the value after --token= (sha256~…) and the URL after --server=.

Then set OPENSHIFT_SERVER + OPENSHIFT_TOKEN. (Console tokens are short-lived; grab a fresh one when it expires, or use username/password below, which re-logs in automatically.)

Configure

{
  "mcpServers": {
    "openshift": {
      "command": "npx",
      "args": ["-y", "@dockndevai/mcp-openshift"],
      "env": {
        "OPENSHIFT_SERVER": "https://api.cluster.example.com:6443",
        "OPENSHIFT_TOKEN": "sha256~...",
        "OPENSHIFT_MODE": "read-only"
      }
    }
  }
}

See docs/CLIENTS.md for Claude Code / Cursor / Codex / VS Code / Windsurf, and .env.example for every variable.

Authentication

Auth mode is chosen automatically (override with OPENSHIFT_AUTH):

• token — OPENSHIFT_TOKEN (bearer). From the console (above) or oc whoami -t.
• password — OPENSHIFT_USERNAME + OPENSHIFT_PASSWORD against the cluster's built-in OAuth server (HTPasswd / LDAP / any challenge-capable local IdP). The server runs the same request-token flow oc login -u … -p … uses, caches the token at ~/.mcp-openshift/token.json (0600), and re-logs in on expiry. The password is sent only to your cluster's OAuth endpoint and is never logged or written to disk.

TLS: clusters usually use a private CA — set OPENSHIFT_CA_CERT to the CA bundle, or (dev only) OPENSHIFT_INSECURE_TLS=true to skip verification.

Safe by default

Enforced by src/security.ts — defence in depth on top of your account's cluster RBAC:

• OPENSHIFT_MODE — read-only (default) → read-write → admin. Tools above the mode aren't registered.
• OPENSHIFT_NAMESPACE_ALLOWLIST / OPENSHIFT_PROTECTED_NAMESPACES — confine writes to named namespaces; system namespaces (kube-*, openshift, openshift-*, default) are readable but never mutable.
• OPENSHIFT_ALLOW_APPLY — creating/updating resources needs this flag on top of read-write, plus a human confirmation.
• OPENSHIFT_ALLOW_DELETE — deletes need admin mode plus this flag, plus confirmation.
• OPENSHIFT_DRY_RUN — sends writes with Kubernetes dryRun=All: validated and admission-checked, but nothing persists.
• Human-in-the-loop — apply, delete, and scale-to-zero pause and ask a person to approve via MCP elicitation.
• OPENSHIFT_AUDIT_LOG — a JSON audit line per guarded op on stderr; Secret values are redacted from all output.

Optional AI risk guard. Set OPENSHIFT_GUARD_MODE=monitor|enforce to have apply_resource / delete_resource consult a local laya-guard daemon (pipx install laya-guard && laya-guard) that classifies the operation allow/confirm/block before it runs. Runs after the apply/delete gates; only tightens, never grants; fails closed.

There is a bundled skill, openshift-safe-operations, that teaches an agent how to authenticate (including from the browser console), the safety rules, and the standard triage/operate workflows. See also SECURITY.md.

Developing

npm install
npm run build
# list the tools without a live cluster:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | OPENSHIFT_SERVER=https://x:6443 OPENSHIFT_TOKEN=x node dist/index.js
npm test

Licence

MIT