mcp-kubeadm-server

Hawaiideveloper/mcp-kubeadm-server

3.2

If you are the rightful owner of mcp-kubeadm-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server for managing Kubernetes clusters with kubeadm on Ubuntu systems using Calico networking.

Kubeadm MCP Server

A Model Context Protocol (MCP) server for managing Kubernetes clusters with kubeadm on Ubuntu systems using Calico networking.

🚀 Quick Start with AI Integration

Want to get started with AI-powered Kubernetes management in 5 minutes?

👉

Perfect for VS Code with GitHub Copilot and Cursor users who want AI assistance with cluster management!

🎯 One-Line Setup

./start.sh

Then configure your editor:

VS Code: Add to settings.json:

{
  "github.copilot.chat.experimental.modelContextProtocol": {
    "enabled": true,
    "servers": {
      "kubeadm-mcp": {
        "command": "curl",
        "args": ["-X", "POST", "http://localhost:3000/mcp", "-H", "Content-Type: application/json", "-d", "@-"],
        "description": "Kubernetes cluster management with kubeadm"
      }
    }
  }
}

Test: Open Copilot Chat and try: @kubeadm help me set up a cluster

Quick Start

Prerequisites

  • Ubuntu 20.04+ (recommended: Ubuntu 22.04 LTS)
  • Docker installed and running
  • Root or sudo access
  • Minimum 2 CPU cores, 2GB RAM

1. Docker Setup (Recommended)

# Build the MCP server
docker build -t kubeadm-mcp-server .

# Run the MCP server
docker run -it --rm \
  --name kubeadm-mcp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.kube:/root/.kube \
  --network host \
  kubeadm-mcp-server

2. Direct Installation

# Install Python 3.8+ and pip
sudo apt update
sudo apt install -y python3 python3-pip python3-venv

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip3 install -r requirements.txt

# Start the MCP server
python3 src/main.py start

# Or use npm scripts (if you prefer)
npm run start

Kubernetes Cluster Setup Checklist

Phase 1: System Preparation

  • Update Ubuntu system

    sudo apt update && sudo apt upgrade -y

  • Install required packages

    sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release

  • Disable swap (required for Kubernetes)

    sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

  • Configure kernel modules

    cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

  • Configure sysctl parameters

    cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sudo sysctl --system

Phase 2: Container Runtime (containerd)

  • Install containerd

    curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y containerd.io

  • Configure containerd for Kubernetes

    sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml
sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml
sudo systemctl restart containerd
sudo systemctl enable containerd

Phase 3: Kubernetes Installation

  • Add Kubernetes APT repository

    curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.29/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

  • Install Kubernetes components

    sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

Phase 4: Initialize Kubernetes Cluster

  • Initialize cluster with custom CIDR

    sudo kubeadm init \
  --pod-network-cidr=172.100.10.0/24 \
  --service-cidr=10.96.0.0/12 \
  --apiserver-advertise-address=$(hostname -I | awk '{print $1}')

  • Configure kubectl for regular user

    mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

Phase 5: Install Calico CNI

  • Download Calico manifest

    curl https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/calico.yaml -O

  • Configure Calico for custom CIDR (172.100.10.0/24)

    # Edit the calico.yaml file to match our CIDR
sed -i 's|# - name: CALICO_IPV4POOL_CIDR|  - name: CALICO_IPV4POOL_CIDR|g' calico.yaml
sed -i 's|#   value: "192.168.0.0/16"|    value: "172.100.10.0/24"|g' calico.yaml

  • Apply Calico networking

    kubectl apply -f calico.yaml

  • Verify Calico pods are running

    kubectl get pods -n kube-system -l k8s-app=calico-node
kubectl get pods -n kube-system -l k8s-app=calico-kube-controllers

Phase 6: Verification

  • Check cluster status

    kubectl get nodes -o wide
kubectl get pods -A

  • Verify networking configuration

    # Check if CIDR is correctly configured
kubectl cluster-info dump | grep -m 1 cluster-cidr
kubectl get ippool -o yaml

  • Test pod networking

    # Deploy test pod
kubectl run test-pod --image=nginx --restart=Never
kubectl get pod test-pod -o wide

# Verify pod gets IP from 172.100.10.0/24 range
kubectl exec test-pod -- ip addr show eth0

# Cleanup
kubectl delete pod test-pod

Phase 7: Optional - Remove Taint (Single Node)

  • Remove master taint for single-node cluster 
    kubectl taint nodes --all node-role.kubernetes.io/control-plane-

Network Configuration Details

Calico with Custom CIDR (172.100.10.0/24)

  • Pod Network CIDR: 172.100.10.0/24
  • Service Network CIDR: 10.96.0.0/12
  • CNI Plugin: Calico v3.26.1
  • IP Pool: 172.100.10.0/24

Verification Commands

# Check IP pool configuration
kubectl get ippool default-ipv4-ippool -o yaml

# Verify Calico status
sudo calicoctl node status

# Check networking
kubectl get nodes -o wide
kubectl describe node $(hostname)

Troubleshooting

Common Issues

  1. Pods stuck in Pending state

    kubectl describe pod <pod-name>
kubectl logs -n kube-system -l k8s-app=calico-node

  2. Node NotReady status

    kubectl describe node $(hostname)
systemctl status kubelet
journalctl -xeu kubelet

  3. Networking issues

    # Check Calico status
kubectl get pods -n kube-system | grep calico

# Verify IP assignment
kubectl get pods -o wide

Reset Cluster (if needed)

sudo kubeadm reset -f
sudo rm -rf /etc/kubernetes/
sudo rm -rf ~/.kube/
sudo rm -rf /var/lib/etcd/

Testing Coverage

Our MCP Kubeadm Server has comprehensive testing with 100% pass rate (56/56 tests):

✅ Unit Tests (38/38 PASSED)

  • DatabaseManager: Document storage, search, configuration management
  • DocumentationFetcher: Content parsing, command extraction, error handling
  • MCPServer: Tool calls, error handling, server operations
  • KubeadmManager: Cluster operations and management

✅ Integration Tests (12/12 PASSED)

  • Database+Fetcher Integration: End-to-end document workflows
  • MCP Server+Database Integration: Tool calls with real database operations
  • MCP Server+Kubeadm Integration: Complete cluster management workflows
  • Complete Workflow Integration: Full user scenarios and error recovery

✅ Performance Tests (6/6 PASSED)

  • Database Performance: 329 docs/second insertion, 589 searches/second
  • MCP Server Performance: 2ms average response time, 699 calls/second concurrent
  • Memory Efficiency: 0.004MB per document, no memory leaks detected

Running Tests

# Run all tests (56 total)
pytest tests/ -v

# Run specific test categories
pytest tests/test_mcp_server.py -v      # Unit tests (38)
pytest tests/test_integration.py -v     # Integration tests (12)
pytest tests/test_performance.py -v     # Performance tests (6)

# Run with coverage
pytest tests/ --cov=src --cov-report=html

Performance Benchmarks

  • Search Response Time: 29ms average (target: <100ms) ✅ 3.4x faster
  • Tool Call Response: 2ms average (target: <500ms) ✅ 250x faster
  • Concurrent Processing: 699 calls/second ✅ 70x target performance
  • Memory Usage: 0.004MB per document ✅ Extremely efficient

See for detailed performance analysis.

MCP Server Usage

Once the cluster is ready, you can use the MCP server to:

  • Deploy applications
  • Manage cluster resources
  • Monitor cluster health
  • Scale workloads
  • Troubleshoot issues

The MCP server provides a convenient interface for common Kubernetes operations while ensuring best practices for Ubuntu deployments with Calico networking.

Support