📦 MCP Box

A local Kubernetes playground for Model Context Protocol (MCP) servers, powered by Kind and the MCP Lifecycle Operator.

Spin up a fully working MCP environment on your machine in minutes — a Kind cluster, the operator that manages MCP server lifecycles, a ready-to-use Kubernetes MCP Server instance, and the MCP Launcher web UI for browsing and deploying MCP servers from a catalog.

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                   Kind Cluster                      │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │  mcp-lifecycle-operator-system                │  │
│  │  └─ MCP Lifecycle Operator (controller)       │  │
│  └───────────────────────────────────────────────┘  │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │  kubernetes-mcp-server                        │  │
│  │  ├─ MCPServer CR (kubernetes-mcp-server)      │  │
│  │  ├─ ServiceAccount (mcp-editor)               │  │
│  │  └─ ConfigMap (server config)                 │  │
│  └───────────────────────────────────────────────┘  │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │  mcp-system                                   │  │
│  │  └─ MCP Launcher (web UI)                     │  │
│  └───────────────────────────────────────────────┘  │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │  mcp-catalog                                  │  │
│  │  └─ Catalog ConfigMaps (server entries)       │  │
│  └───────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────┘

📋 Prerequisites

• Kind installed
• kubectl installed
• A container runtime — Podman (Linux) or Docker (macOS)

🚀 Getting Started

Run everything with a single command:

./mcp-box.sh

Or run individual steps from the scripts/ directory:

./scripts/00-installer-kind.sh          # 1. Create a Kind cluster
./scripts/01-mcp-lifecycle-operator.sh  # 2. Install the MCP Lifecycle Operator
./scripts/02-kubernetes-mcp-server.sh   # 3. Deploy the Kubernetes MCP Server
./scripts/03-mcp-launcher.sh           # 4. Deploy the MCP Launcher (web UI + catalog)

🔍 What Each Script Does

Script	Description
mcp-box.sh	Wrapper that runs all scripts below in order.
scripts/00-installer-kind.sh	Creates a Kind cluster (uses Podman on Linux), waits for core services, and patches CoreDNS to use 8.8.8.8 for external resolution.
scripts/01-mcp-lifecycle-operator.sh	Installs the MCP Lifecycle Operator from the upstream distribution manifest and waits for the controller deployment to become ready.
scripts/02-kubernetes-mcp-server.sh	Creates the kubernetes-mcp-server namespace, a ServiceAccount with edit permissions, a server configuration ConfigMap, and an MCPServer custom resource that the operator reconciles into a running MCP server pod.
scripts/03-mcp-launcher.sh	Installs the MCP Launcher web UI from its distribution manifest. Creates the mcp-system and mcp-catalog namespaces with RBAC, a Deployment/Service, and sample catalog entries.

✅ Verifying the Setup

After running all scripts, confirm everything is healthy:

kubectl get pods -A

You should see pods running in kube-system, mcp-lifecycle-operator-system, kubernetes-mcp-server, and mcp-system.

Check the MCP server resource:

kubectl get mcpservers -n kubernetes-mcp-server

🔌 Port Forwarding

To connect to the MCP server from your local machine (e.g. from a local MCP client or Claude Desktop):

kubectl port-forward -n kubernetes-mcp-server svc/kubernetes-mcp-server 8080:8080

The server will be available at http://localhost:8080/mcp.

To access the MCP Launcher web UI:

kubectl port-forward -n mcp-system svc/mcp-launcher 9090:8080

Then open http://localhost:9090 in your browser.

🔎 MCP Inspector

You can use the MCP Inspector to test and debug the MCP server. First, port-forward the MCP server as shown above, then run the inspector locally:

podman run --rm --network host ghcr.io/modelcontextprotocol/inspector:latest

Open http://localhost:6274 in your browser and connect to http://localhost:8080/mcp.

🧹 Cleanup

Delete the entire Kind cluster:

kind delete cluster

📄 License

Apache License 2.0