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.

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. For a namespace or project the check is on its own name.
• `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. The prompt shows the tool, the exact arguments and a fingerprint; the target's uid@resourceVersion is pinned across the prompt and the action is refused if it changed; a prompt nobody answers is a refusal. Deleting a namespace or project also asks the human to type its name.
• `OPENSHIFT_REQUIRE_HUMAN_APPROVAL` (default false) — when true, apply / delete / scale-to-zero are refused if the client cannot elicit (instead of falling back to the OPENSHIFT_ALLOW_* gate alone).
• `OPENSHIFT_AUDIT_LOG` — a JSON audit line per guarded op on stderr; Secret values are redacted from resource reads, lists and delete/scale responses.
• `OPENSHIFT_REDACT_LOGS` (default true) — pod_logs output is scrubbed of credential-shaped text (PEM private keys, password=/token: style pairs, Authorization/Bearer values, URL passwords, JWTs and service-account tokens, AWS/GCP/GitHub/Slack/... key shapes) before it reaches the model. Best-effort heuristics, not a guarantee (a bare random password is not caught); set false to return raw logs. See SECURITY.md for exactly what is and is not caught.
• `OPENSHIFT_REDACT_OBJECTS` (default true) — get_resource, list_resources / list_events, and the objects returned by delete_resource / scale mask credential-shaped content that is not in a Secret: env values whose variable name looks secret (DB_PASSWORD, API_KEY, *_TOKEN, *_DSN, ... in pods and in every pod template: Deployments, DeploymentConfigs, StatefulSets, Jobs, CronJobs, Builds, Templates; valueFrom references stay visible), ConfigMap entries with secret-shaped keys or credential-looking values, Route tls.key, BuildConfig webhook secrets, command-line --password x arguments, URL passwords, and the copy of all of it in the last-applied-configuration annotation. Best-effort and by name: a credential under an innocuous name is not caught. Set false to return these objects unchanged. Secret values are always redacted and not affected by this setting. See SECURITY.md.

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