Configuration

Environment Variables

The MCP server reads all backend service URLs from environment variables at startup. Every one of them defaults to http://localhost:<port> in the code itself — that default is what makes the server usable out of the box against services reached via kubectl port-forward during local development, and it's why the in-cluster example further down explicitly overrides every single one rather than relying on defaults.

Service URLs

Variable	Default	Service
K8S_MONITOR_BASE_URL	http://localhost:8085	k8s-monitor — health, cost, metrics
SECURITY_API_BASE_URL	http://localhost:8086	security-api — posture, vulnerabilities
CICD_GATEWAY_BASE_URL	http://localhost:8087	cicd-gateway — pipeline run history
KUBEOPERA_API_BASE_URL	http://localhost:8080	kubeopera-api — apps, deployments, pipelines, builds
ANOMALY_DETECTOR_BASE_URL	http://localhost:8088	anomaly-detector — anomaly events
PREDICTIVE_SCALER_BASE_URL	http://localhost:8089	predictive-scaler — forecasts and scaling
INCIDENT_MANAGER_BASE_URL	http://localhost:8090	incident-manager — incidents and runbooks
OBSERVABILITY_AGENT_SRV_BASE_URL	http://localhost:8092	observability-agent — telemetry
ANALYSIS_AGENT_SRV_BASE_URL	http://localhost:8093	analysis-agent — analysis results
ACTION_AGENT_SRV_BASE_URL	http://localhost:8094	action-agent — action log
FEEDBACK_AGENT_SRV_BASE_URL	http://localhost:8095	feedback-agent — feedback signals
RECOMMENDATION_AGENT_SRV_BASE_URL	http://localhost:8096	recommendation-agent — AI recommendations
AGENT_RUNTIME_BASE_URL	http://localhost:8111	agent-runtime — agent launcher
NODES_MANAGER_BASE_URL	http://localhost:8115	nodes-manager — node lifecycle, Karpenter
LOG_GATEWAY_BASE_URL	http://localhost:3100	log-gateway — pod/deployment logs
SLO_MANAGER_BASE_URL	http://localhost:9090	slo-manager — SLO compliance, error budgets
APM_GATEWAY_BASE_URL	http://localhost:9090	apm-gateway — application performance metrics
TRACING_GATEWAY_BASE_URL	http://localhost:16686	tracing-gateway — distributed traces
RCA_ENGINE_BASE_URL	http://localhost:8116	rca-engine — root-cause analysis
KUBEOPERA_AI_BASE_URL	http://localhost:8113	Optimizer — health/optimize/troubleshoot
APP_ADVISOR_BASE_URL	http://localhost:8105	app-advisor-srv — per-app domain profile and advice

The four GitOps tools (sync_argocd_app, get_argocd_app_status, push_gitops_patch, trigger_flux_reconcile) read a separate set of variables — ARGOCD_API_URL, ARGOCD_TOKEN, FLUX_WEBHOOK_URL, FLUX_WEBHOOK_TOKEN, GITOPS_REPO_API_URL, GITOPS_REPO_TOKEN — since they talk to Argo CD and a Git hosting API directly rather than to another KubeOpera backend service.

Other Variables

The MCP server itself has no other required environment variables. The Anthropic API key is used by agent-runtime, not the MCP server.

---

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Minimal (read-only tools, k8s-monitor only)

{
  "mcpServers": {
    "kubeopera": {
      "command": "/path/to/kubeopera-mcp-server",
      "args": ["--toolsets", "kubeopera"],
      "env": {
        "K8S_MONITOR_BASE_URL": "http://k8s-monitor:8085"
      }
    }
  }
}

Full Platform (all 49 tools)

{
  "mcpServers": {
    "kubeopera": {
      "command": "/path/to/kubeopera-mcp-server",
      "args": ["--toolsets", "kubeopera"],
      "env": {
        "K8S_MONITOR_BASE_URL":              "http://localhost:8085",
        "SECURITY_API_BASE_URL":             "http://localhost:8086",
        "CICD_GATEWAY_BASE_URL":             "http://localhost:8087",
        "KUBEOPERA_API_BASE_URL":            "http://localhost:8080",
        "ANOMALY_DETECTOR_BASE_URL":         "http://localhost:8088",
        "PREDICTIVE_SCALER_BASE_URL":        "http://localhost:8089",
        "INCIDENT_MANAGER_BASE_URL":         "http://localhost:8090",
        "OBSERVABILITY_AGENT_SRV_BASE_URL":  "http://localhost:8092",
        "ANALYSIS_AGENT_SRV_BASE_URL":       "http://localhost:8093",
        "ACTION_AGENT_SRV_BASE_URL":         "http://localhost:8094",
        "FEEDBACK_AGENT_SRV_BASE_URL":       "http://localhost:8095",
        "RECOMMENDATION_AGENT_SRV_BASE_URL": "http://localhost:8096",
        "AGENT_RUNTIME_BASE_URL":            "http://localhost:8111"
      }
    }
  }
}

Kubernetes In-Cluster (production)

When running KubeOpera inside Kubernetes, use in-cluster service DNS names:

{
  "mcpServers": {
    "kubeopera": {
      "command": "/path/to/kubeopera-mcp-server",
      "args": ["--toolsets", "kubeopera"],
      "env": {
        "K8S_MONITOR_BASE_URL":              "http://k8s-monitor.kubeopera.svc.cluster.local:8085",
        "SECURITY_API_BASE_URL":             "http://security-api.kubeopera.svc.cluster.local:8086",
        "CICD_GATEWAY_BASE_URL":             "http://cicd-gateway.kubeopera.svc.cluster.local:8087",
        "KUBEOPERA_API_BASE_URL":            "http://kubeopera-api.kubeopera.svc.cluster.local:8080",
        "ANOMALY_DETECTOR_BASE_URL":         "http://anomaly-detector.kubeopera.svc.cluster.local:8088",
        "PREDICTIVE_SCALER_BASE_URL":        "http://predictive-scaler.kubeopera.svc.cluster.local:8089",
        "INCIDENT_MANAGER_BASE_URL":         "http://incident-manager.kubeopera.svc.cluster.local:8090",
        "OBSERVABILITY_AGENT_SRV_BASE_URL":  "http://observability-agent-srv.kubeopera.svc.cluster.local:8092",
        "ANALYSIS_AGENT_SRV_BASE_URL":       "http://analysis-agent-srv.kubeopera.svc.cluster.local:8093",
        "ACTION_AGENT_SRV_BASE_URL":         "http://action-agent-srv.kubeopera.svc.cluster.local:8094",
        "FEEDBACK_AGENT_SRV_BASE_URL":       "http://feedback-agent-srv.kubeopera.svc.cluster.local:8095",
        "RECOMMENDATION_AGENT_SRV_BASE_URL": "http://recommendation-agent-srv.kubeopera.svc.cluster.local:8096",
        "AGENT_RUNTIME_BASE_URL":            "http://agent-runtime.kubeopera.svc.cluster.local:8111"
      }
    }
  }
}

---

Claude Code Configuration

Via CLI

claude mcp add kubeopera \
  --command /path/to/kubeopera-mcp-server \
  --args "--toolsets kubeopera" \
  --env K8S_MONITOR_BASE_URL=http://localhost:8085 \
  --env SECURITY_API_BASE_URL=http://localhost:8086 \
  --env AGENT_RUNTIME_BASE_URL=http://localhost:8111

Via .mcp.json

Create .mcp.json in your project root:

{
  "mcpServers": {
    "kubeopera": {
      "command": "/path/to/kubeopera-mcp-server",
      "args": ["--toolsets", "kubeopera"],
      "env": {
        "K8S_MONITOR_BASE_URL": "http://localhost:8085",
        "AGENT_RUNTIME_BASE_URL":            "http://localhost:8111"
      }
    }
  }
}

---

Toolset Selection

The --toolsets flag controls which tool groups are loaded. You can combine multiple toolsets:

# KubeOpera tools only
./kubeopera-mcp-server --toolsets kubeopera

# KubeOpera + core Kubernetes tools
./kubeopera-mcp-server --toolsets kubeopera,core

# All available toolsets
./kubeopera-mcp-server --toolsets all

Available toolsets — kubeopera is this fork's own addition; the rest are inherited unmodified from the upstream containers/kubernetes-mcp-server project this server is built on:

Toolset	Description
kubeopera	All 49 KubeOpera platform tools (see the full reference)
core	Standard kubectl-equivalent tools
config	Kubeconfig and cluster-context management
helm	Helm chart management
tekton	Tekton pipeline tools
kiali	Service mesh topology and health via Kiali
kubevirt	KubeVirt VM management

---

Building from Source

git clone https://github.com/ochestra-tech/kubeopera-mcp-server
cd kubeopera-mcp-server
go mod tidy
go build -o kubeopera-mcp-server ./cmd/server

Requirements: Go 1.22+

---

Verifying the Installation

List all tools

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | K8S_MONITOR_BASE_URL=http://localhost:8085 \
    ./kubeopera-mcp-server --toolsets kubeopera

The response should include all 49 KubeOpera tools in the result.tools array.

Test a tool call

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_cluster_health","arguments":{}}}' \
  | K8S_MONITOR_BASE_URL=http://localhost:8085 \
    ./kubeopera-mcp-server --toolsets kubeopera

Test an agent launcher

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run_sre_agent","arguments":{"cluster_id":"local","prompt":"Check cluster health and summarize findings"}}}' \
  | AGENT_RUNTIME_BASE_URL=http://localhost:8111 \
    ./kubeopera-mcp-server --toolsets kubeopera

The response includes a run_id. Stream the agent's live reasoning:

curl -N http://localhost:8111/api/v1/runs/{run_id}/stream

---

HTTP Timeout

Each tool call uses a 15-second HTTP timeout when querying backend services. If a backend service is unavailable, the tool returns an error message — it does not cause the MCP server to crash or block other tools.

---

Transport

Everything on this page so far describes the common case: the MCP server run over stdio transport, launched as a subprocess by the AI client (Claude Desktop, Claude Code) and communicating over stdin/stdout, with no network port opened at all. This needs no firewall configuration, keeps every backend service URL reachable only from the machine running the client, and gives each new conversation a fresh, isolated server process.

Because this server is a fork of containers/kubernetes-mcp-server, it also inherits that project's --port flag, which starts a standalone streamable-HTTP/SSE server instead — useful when the MCP server needs to be reachable over the network rather than launched locally per client, for instance as a shared team deployment. That mode brings its own considerations (the server now needs to be reachable, so it needs the same care around network exposure and auth as any other backend service) that don't apply to the stdio case above; consult the upstream project's own documentation for the full set of HTTP-mode flags, since none of them are KubeOpera-specific.