How jbrcoleman/mcp-server-eks works
Project Type and Purpose
• This is a deployment-focused project that provisions AWS resources (EKS cluster, node pools, autoscaler) via Terraform, builds and publishes a Dockerized Python MCP (Model Context Protocol) server to ECR, and then deploys it into Kubernetes (EKS) with optional Karpenter autoscaling. It also provides a Python client example and integration with Claude Desktop.
File Structure
Top-level:
• server-enhanced.py / client-example.py – MCP server code and test client
• Dockerfile / requirements.txt – container build and Python dependencies
• terraform/ – AWS infra modules
– main.tf, variables.tf, outputs.tf – core EKS and networking
– karpenter/ – Helm chart definition for Karpenter autoscaler
• k8s/ – Kubernetes manifests (Namespace, ConfigMap, Deployment, Service)
• scripts/ – orchestration scripts (deploy.sh, terraform-init.sh, test-deployment.sh)
• Makefile – legacy deployment shortcuts
• integrate-with-claude.md + claude-desktop-config.json – external integration
README Insights
• Architecture section clearly delineates components: Python MCP server, Docker container, EKS/Kubernetes, Karpenter, Terraform.
• Deployment section calls out three phases (infra, karpenter, app) and legacy vs. recommended flows.
Main Components
A. Infrastructure Layer (Terraform)
• AWS Account: IAM, ECR, VPC, Subnets, Security Groups
• EKS Control Plane (AWS-managed)
• Node Groups:
– Managed Node Group (bootstrap, minimal nodes)
– Karpenter Provisioner → EC2NodeClass, NodePool, Spot/On-Demand
B. Container Registry
• ECR Repository hosting the MCP Server image
C. Kubernetes Layer (EKS Cluster)
• Namespace (mcp-server)
• ConfigMap (application config)
• Deployment (MCP Server Pods)
• Service (ClusterIP or LoadBalancer exposing the server)
• Karpenter Controller (running as a Helm chart in the cluster)
D. Application Layer
• MCP Server (Python code) – connects to Kubernetes API for cluster metrics
• Client Example (Python) – demonstrates programmatic usage
• Claude Desktop (external user interface) – talks to MCP Server via REST/gRPC
E. Management & CI/CD
• Scripts (deploy.sh, terraform-init, test-deployment)
• Makefile (legacy commands)
Relationships and Data Flows
• Terraform → AWS resources (EKS, IAM, ECR)
• Docker build → pushes image to ECR
• kubectl / scripts → deploys k8s manifests to EKS
• Karpenter Controller watches unscheduled pods → requests new nodes via AWS API (Terraform-managed IAM roles)
• MCP Server Pod → Kubernetes API for get_cluster_status, list_pods, get_deployments
• Client / Claude Desktop → HTTP/gRPC requests → Service → Pod
Architectural Patterns and Principles
• Infrastructure as Code (Terraform modules)
• Containerization (Dockerfile + ECR)
• Declarative Orchestration (Kubernetes manifests)
• Autoscaling (Karpenter as a Kubernetes-native autoscaler)
• Separation of Concerns: infra vs. orchestration vs. application vs. client
• Notes on environment variables (AWS_REGION, CLUSTER_NAME, IMAGE_TAG) and configuration sources (ConfigMap, claude-desktop-config.json)