Skip to main content
Glama

mcp-openshift

npm CI licence

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

Related MCP server: Kubernetes MCP Server

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

Available Tools

6 tools
get_resourceGet a resourceA
Read-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 eventsA
Read-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 projectsA
Read-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 resourcesA
Read-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 logsB
Read-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 IA
Read-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

    A3.9/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      9
      10 npm
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      49
      MIT