dockndevai/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
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
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.