Development Environment - cturner8/kube-mcp GitHub Wiki

This guide helps you set up a reliable development environment for kube-mcp. You can use the provided devcontainers or set things up manually.

Requirements

Required

  • Go 1.25.x
  • Docker (or Podman) with BuildKit enabled
  • A Kubernetes cluster for development (kind, minikube, k3d, or remote)
  • Git

Optional but recommended

  • kubectl (tested with 1.29+)
  • Helm 3.x
  • VS Code + Dev Containers extension
  • k9s (already included in the devcontainers)

Quickstart: devcontainer

Two devcontainer variants are provided under the .devcontainer directory:

  • k8s:
    • kubectl
    • helm
    • k9s
    • connect to an existing cluster (no embedded Minikube).
  • minikube:
    • kubectl
    • helm
    • k9s
    • minikube
    • docker-in-docker
    • boots a local Minikube inside the container with dashboard, metrics-server, and ingress enabled.

Steps (VS Code):

  1. Install Docker and the β€œDev Containers” extension.
  2. Open the repo folder in VS Code, then Reopen in Container either from the Command Palette or the Remote Icon in bottom left corner.
  3. Choose the variant you want (minikube or k8s).
    • minikube will run minikube start --addons=dashboard,metrics-server,ingress on start.
  4. Ports 8000/8080/8443 are forwarded by default; adjust as needed in the devcontainer config.

Manual environment setup

  1. Install prerequisites
    • Go 1.25.x
    • Docker/Podman
    • kubectl
    • Helm
    • preferred local cluster tool (kind/minikube/k3d).
  2. Clone the repository 
    git clone https://github.com/cturner8/kube-mcp.git
cd kube-mcp
  3. Fetch Go dependencies and run a quick check 
    cd api
go mod download
go build .
  4. (Optional) Lint Helm charts 
    helm lint charts/kube-mcp
  5. Ensure your kubeconfig points to the dev cluster you plan to use 
    kubectl config get-contexts
 kubectl config use-context <your-dev-context>

Create a dev cluster

If you don't have an existing Kubernetes cluster, you'll need to create a local one for development and testing. Choose the tool that best fits your workflow:

Using minikube

Minikube is the easiest option for beginners and is included in the minikube devcontainer. It creates a single-node Kubernetes cluster inside a VM or using Docker.

Quick start:

minikube start --addons=dashboard,metrics-server,ingress

This enables the dashboard, metrics server for monitoring, and ingress controller – all useful for kube-mcp development.

Using kind

kind (Kubernetes in Docker) is ideal if you're familiar with Docker and want a lightweight, multi-node cluster that works well in CI/CD pipelines.

Quick start with port forwarding for kube-mcp:

cat <<EOF | kind create cluster --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 80
    hostPort: 80
    protocol: TCP
  - containerPort: 443
    hostPort: 443
    protocol: TCP
EOF

This configuration forwards HTTP and HTTPS ports, useful if you're testing kube-mcp behind an ingress.

Using k3d

k3d wraps k3s (lightweight Kubernetes) in Docker, offering a good balance between simplicity and features. It starts faster than minikube and is more configurable than basic kind setups.

Quick start:

k3d cluster create kube-mcp-dev --port 8080:80@loadbalancer --port 8443:443@loadbalancer

This creates a cluster named kube-mcp-dev with load balancer port forwarding.

Configuration for local development

The server reads configuration from flags or environment variables. Key settings (required):

  • KUBE_MCP_BASE_URL (required) – base URL the app is accessed from.
  • KUBE_MCP_OIDC_ISSUER_URL (required) – OIDC issuer.
  • KUBE_MCP_OIDC_CLIENT_ID (required) – client ID.

Additional optional settings:

  • KUBE_MCP_ALLOWED_ORIGINS – comma-separated CORS origins.
  • KUBE_MCP_PORT – defaults to 9000.
  • KUBE_MCP_LOG_LEVEL – debug|info|warn|error (default info).
  • KUBE_MCP_ALLOWED_TOOLS / KUBE_MCP_DISALLOWED_TOOLS – comma-separated allow/deny lists (only one may be set).
  • KUBE_MCP_OIDC_SCOPES – comma-separated scopes (default: openid).
  • KUBE_MCP_OIDC_SIGNING_METHOD – HS256 or RS256.

Run the API locally (out of cluster)

cd kube-mcp/api
go run . \
  --base-url "http://localhost:9000" \
  --oidc-issuer-url "https://auth.localhost:8443" \
  --oidc-client-id "00000000-0000-0000-0000-000000000000" \
  --out-of-cluster \
  • By default the kubeconfig is loaded from $HOME/.kube/config, use the --kubeconfig flag to use a different kubeconfig.
  • Add --allowed-tools or --disallowed-tools if you need to constrain tool access.
  • Override the port with --port or KUBE_MCP_PORT.
  • Add allowed origins if accessing from the browser (useful for MCP inspector).

Verify your setup

  • Go toolchain: go version
  • Docker: docker info
  • kubectl: kubectl version --client --short
  • Helm: helm version --short
  • Cluster reachable: kubectl get nodes

Understanding the codebase

Before diving into development, familiarise yourself with the project structure:

kube-mcp/
β”œβ”€β”€ api/              # Go application source code
β”‚   β”œβ”€β”€ main.go       # Application entry point and server startup
β”‚   β”œβ”€β”€ config/       # Configuration management (CLI flags, environment variables)
β”‚   β”œβ”€β”€ server/       # HTTP server implementation and MCP protocol handlers
β”‚   β”œβ”€β”€ kubernetes/   # Kubernetes client setup and API interactions
β”‚   └── tools/        # MCP tool implementations (one file per tool)
β”œβ”€β”€ charts/           # Helm deployment configuration
β”‚   └── kube-mcp/     # Main Helm chart with templates and values
β”œβ”€β”€ .devcontainer/    # VS Code development container configurations
β”‚   β”œβ”€β”€ k8s/          # Devcontainer for connecting to existing clusters
β”‚   └── minikube/     # Devcontainer with embedded Minikube
└── .github/workflows/ # GitHub Actions CI/CD automation
    β”œβ”€β”€ test.yml      # Build and test workflow
    β”œβ”€β”€ build.yml     # Container image build workflow
    └── helm.yml      # Helm chart publication workflow

Key directories

  • api/ – Contains the Go application. Most development happens here. The entry point is main.go, which initialises the HTTP server and loads configuration.
  • api/tools/ – Each MCP tool (e.g., list_pods, get_deployment) has its own file following a consistent implementation pattern.
  • charts/ – Helm templates and values for deployment. Modify when changing deployment configuration or adding new Helm features.
  • .devcontainer/ – Pre-configured development environments for VS Code. Contains both a standalone Minikube variant and a variant for connecting to existing clusters.
  • .github/workflows/ – Automated testing and release workflows. Typically read-only during development, but useful to understand for CI/CD troubleshooting.

Next steps

  • Explore the api/main.go file to understand server initialisation and configuration loading.
  • Review api/tools/ to see how MCP tools are implemented.