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 namespace

... View full README on GitHub