Overview

The MCP (Model Context Protocol) Kubernetes server provides a lightweight HTTP API to manage Kubernetes workloads — specifically pods, deployments, and services — through a consistent, scriptable interface. It acts as a bridge between operator tooling (or other control planes) and a Kubernetes cluster, allowing you to inspect resource state, push updates, and observe health without embedding Kubernetes client libraries in every consumer.

This server is useful when you need a small, language-agnostic control endpoint for cluster operations: CI/CD runners can trigger rollouts, monitoring systems can probe health and uptime, and automation scripts can query or reconcile deployments. The server supports both out-of-cluster operation using a kubeconfig and in-cluster operation using the Kubernetes service account, and it can be configured to require TLS and token-based authentication for secure access.

Features

Manage core Kubernetes resources: pods, deployments, and services
Read and list resource state and metadata
Trigger updates/rollouts to deployments (image updates)
Expose health and readiness endpoints for monitoring
Support for in-cluster and kubeconfig authentication
Optional TLS and token-based authentication for secure access
Simple HTTP/JSON API usable from curl, CI systems, and scripting languages

Installation / Configuration

Build from source (Go required):

git clone https://github.com/Flux159/mcp-server-kubernetes.git
cd mcp-server-kubernetes
go build -o mcp-server ./cmd/server

Run locally using a kubeconfig:

./mcp-server \
  --kubeconfig="$HOME/.kube/config" \
  --listen-addr="0.0.0.0:8080" \
  --auth-token="your-secret-token"

Run inside a cluster (in-cluster RBAC must be configured):

# Example Kubernetes Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  replicas: 1
  template:
    spec:
      containers:
      - name: mcp-server
        image: your-registry/mcp-server:latest
        args:
        - --listen-addr=0.0.0.0:8080
        - --use-incluster=true
        env:
        - name: AUTH_TOKEN
          valueFrom:
            secretKeyRef:
              name: mcp-auth
              key: token
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-server
spec:
  selector:
    app: mcp-server
  ports:
  - protocol: TCP
    port: 8080
    targetPort: 8080

Common environment variables / flags:

Flag / Env	Purpose	Default
–kubeconfig	Path to kubeconfig for out-of-cluster access	“”
–use-incluster	Enable in-cluster service account authentication	false
–listen-addr	TCP address to bind the HTTP server	0.0.0.0:8080
–tls-cert, –tls-key	TLS certificate and key paths (optional)	“”
–auth-token / AUTH_TOKEN	Token required for API calls (optional)	“”

Available Resources

The server exposes a concise REST-like API for common operations. Example endpoints (prefix /v1):

GET /v1/pods — list pods (optionally filter by namespace/label)
GET /v1/pods/{namespace}/{name} — get a specific pod
GET /v1/deployments — list deployments
GET /v1/deployments/{namespace}/{name} — get deployment details
POST /v1/deployments/{namespace}/{name}/update — trigger a rollout (e.g., set image)
GET /v1/services — list services
GET /health — health/readiness probe
GET /metrics — Prometheus-style metrics (if enabled)

Authentication is typically via a header (Authorization: Bearer ) when an AUTH_TOKEN is configured. The API uses JSON payloads for POST/PUT operations.

Example: update a deployment image

curl -X POST "https://mcp.example.com/v1/deployments/default/my-app/update" \
  -H "Authorization: Bearer ${MCP_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"container":"app","image":"my-registry/my-app:1.2.3"}'

Use Cases

Continuous Deployment: CI pipelines call the update endpoint to rotate deployment images and initiate controlled rollouts without embedding cluster clients.
Canary and Blue/Green Workflows: Automation scripts query deployment and pod status, then update services to shift traffic after health checks pass.
Lightweight Dashboard Backends: A UI can use the API to list resources and surface basic health without direct kube-apiserver access from the browser.
Monitoring and Alerting: Monitoring systems can poll /health and /metrics for uptime and basic cluster resource health exposed by the server.
Multi-cluster Gateways: Run one instance per cluster to present a consistent control plane for an orchestrator that manages multiple clusters.

Security and Best Practices

Run behind a network boundary (ingress, VPN) and enable TLS for public access.
Configure the server to use in-cluster service account credentials and create a dedicated RBAC role with least privilege for the operations required.
Use token authentication or integrate with your existing API gateway for centralized auth and auditing.
Limit exposed endpoints with network policies or firewall rules to reduce attack surface.

Resources

Source and issues: https://github.com/Flux159/mcp-server-kubernetes
Example usage: see the repo’s examples directory for deployment manifests and sample curl commands

This MCP server is intended as a small, pragmatic control API for Kubernetes clusters — suitable for automation, CI/CD, and lightweight orchestration layers that need stable, scriptable access to pods, deployments, and services.

Tags:developer-tools

Kubernetes MCP Server: Manage Pods, Deployments, Services