mcp-openshift
A safe-by-default MCP server for OpenShift/Kubernetes that lets an agent inspect a cluster read-only, and — in higher modes — operate it.
Confirm identity —
whoamireturns the authenticated user and groups.Discover namespaces —
list_projectslists the projects/namespaces you can see, with display name and phase.List any resource kind —
list_resourcesworks for pods, deployments, deploymentconfigs, routes, services, builds, imagestreams, and more, with optional namespace, label selector, and result limit (capped at 500).Inspect a single object —
get_resourcereturns one resource with full spec/status.Read pod logs —
pod_logsfetches recent container logs, optionally a specific container, the previous (crashed) instance, or a chosen number of tail lines (max 5000, default 200).Triage failures —
list_eventsshows recent namespace events to explain scheduling/startup problems.Safety built in — secret values are always redacted, and logs/objects are scrubbed of credential-shaped content by default.
Mode-gated extras (per README, not in this schema) —
read-writemode addsscaleandrollout_restart;apply_resource(SSA) needs read-write plusOPENSHIFT_ALLOW_APPLY;delete_resourceneeds admin plusOPENSHIFT_ALLOW_DELETE; apply/delete/scale-to-zero prompt a human for approval, with dry-run and audit options.
Provides tools for exploring and operating Kubernetes/OpenShift clusters, including listing projects and resources, reading pods and logs, and (in higher modes) scaling workloads, restarting deployments, applying manifests, and deleting resources.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-openshift list pods in the openshift-console namespace"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| confirm the authenticated identity | read-only |
| projects/namespaces you can see | read-only |
| list any kind (± namespace, label selector) | read-only |
| one resource with full spec/status | read-only |
| a pod's container logs | read-only |
| recent events in a namespace | read-only |
| set replicas on a Deployment/DeploymentConfig | read-write |
| restart a Deployment | read-write |
| create/update from a manifest (SSA) | read-write + |
| delete a resource | admin + |
Related MCP server: Kubernetes MCP Server
Install
npx -y @dockndevai/mcp-openshiftYou 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) oroc whoami -t.password —
OPENSHIFT_USERNAME+OPENSHIFT_PASSWORDagainst the cluster's built-in OAuth server (HTPasswd / LDAP / any challenge-capable local IdP). The server runs the same request-token flowoc 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 KubernetesdryRun=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@resourceVersionis 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(defaultfalse) — whentrue, apply / delete / scale-to-zero are refused if the client cannot elicit (instead of falling back to theOPENSHIFT_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(defaulttrue) —pod_logsoutput is scrubbed of credential-shaped text (PEM private keys,password=/token:style pairs,Authorization/Bearervalues, 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); setfalseto return raw logs. See SECURITY.md for exactly what is and is not caught.OPENSHIFT_REDACT_OBJECTS(defaulttrue) —get_resource,list_resources/list_events, and the objects returned bydelete_resource/scalemask credential-shaped content that is not in a Secret:envvalues 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;valueFromreferences stay visible), ConfigMap entries with secret-shaped keys or credential-looking values, Routetls.key, BuildConfig webhook secrets, command-line--password xarguments, URL passwords, and the copy of all of it in thelast-applied-configurationannotation. Best-effort and by name: a credential under an innocuous name is not caught. Setfalseto 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 testLicence
MIT
Available Tools
6 toolsget_resourceGet a resourceARead-onlyIdempotent
Fetch a single resource by kind + name (+ namespace for namespaced kinds), with its full spec/status. Secret values are redacted.
Inputs: kind (required), name (required), namespace.
list_eventsList eventsARead-onlyIdempotent
List recent events in a namespace — the fastest way to see why something is failing to schedule/start.
Inputs: namespace (required), limit.
list_projectsList projectsARead-onlyIdempotent
List the projects (namespaces) you can see, with name, display name and phase. Start here to find a namespace to work in.
Inputs: no named parameters.
list_resourcesList resourcesARead-onlyIdempotent
List resources of a kind, optionally in a namespace and filtered by a label selector. Returns the raw Kubernetes/OpenShift list (secret values are redacted). Works for core and OpenShift kinds (pods, deployments, deploymentconfigs, routes, services, builds, imagestreams, …).
Inputs: kind (required), limit, namespace, label_selector.
pod_logsPod logsBRead-onlyIdempotent
Read a pod's container logs (most recent lines). Optionally a specific container or the previous instance.
Inputs: name (required), namespace (required), previous, container, +1 more.
whoamiWho am IARead-onlyIdempotent
Return the authenticated user (name and groups) — confirm which identity the server is using.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
The six tools each target a distinct concern: identity, project discovery, generic resource listing, single-resource retrieval, logs, and events. The only mild overlap is list_projects vs list_resources with kind='projects', but the specialized project listing is clearly differentiated by its friendlier return format and explicit 'start here' intent.
Most tools follow a verb_noun pattern (list_projects, list_resources, get_resource, list_events), but whoami and pod_logs break that pattern, one being a bare command and the other a noun_noun compound. The names are still readable, but the conventions are mixed.
Six tools is well-scoped for a read-only OpenShift inspection server. Each tool earns its place and together they form a compact workflow without unnecessary bloat.
The set covers the main diagnostic lifecycle: confirm identity, discover projects, list and fetch resources, read pod logs, and inspect events. It lacks mutating operations like create/update/delete, but the described surface appears intentionally read-only, so the gaps are minor for that purpose.
Maintenance
Related MCP Connectors
Fail-closed policy guardrails for AI agents running kubectl, terraform, helm, and argocd.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with and manage Kubernetes clusters, supporting operations on pods, deployments, services, configmaps, secrets, namespaces, metrics, and events with built-in safety features for destructive actions.910 npm1MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with Kubernetes clusters through 50 specialized tools for comprehensive cluster management. Supports both local kubectl and remote SSH-based execution for managing pods, deployments, services, and other Kubernetes resources.49MIT
- AlicenseBqualityBmaintenanceEnables AI agents to inspect and operate a Kubernetes cluster safely, with read-only mode and namespace allowlist for mutations.1072 PyPI2MIT
- AlicenseAqualityBmaintenanceProvides AI assistants with comprehensive OpenShift/Kubernetes cluster management capabilities through the oc CLI.1458 npm1MIT