MCP Server on EKS

EKS 上的 MCP 服务

此项目使用 Terraform 管理基础设施，在 Amazon EKS 上部署 Model Context Protocol（MCP）服务。

架构

• MCP 服务：使用 Python 实现 MCP 协议的服务
• 容器：用于 MCP 服务的 Docker 容器
• Kubernetes：用于容器编排的 EKS 集群
• Karpenter：原生 Kubernetes 节点自动扩缩器，可实现高效扩缩
• 基础设施：用于管理 AWS 资源的 Terraform

前提条件

• 已配置适当权限的 AWS CLI
• 已安装 Docker
• Terraform >= 1.0
• 已安装 kubectl
• 已创建 ECR 存储库的 AWS 账户

快速开始

1. 设置环境变量：

export AWS_REGION=us-east-1
export AWS_ACCOUNT_ID=your-account-id
export CLUSTER_NAME=mcp-eks-cluster

2. 使用 Karpenter 部署（推荐）：

# Option 1: Deploy everything at once
./scripts/deploy.sh all

# Option 2: Phase-by-phase deployment
./scripts/deploy.sh infrastructure  # Deploy EKS cluster
./scripts/deploy.sh karpenter       # Deploy Karpenter autoscaler
./scripts/deploy.sh app             # Deploy MCP server

3. 旧版部署（不使用 Karpenter）：

make init
make plan
make apply
make deploy

项目结构

├── server-enhanced.py           # MCP server with real Kubernetes API integration
├── client-example.py            # Example MCP client for testing
├── Dockerfile                   # Container definition
├── requirements.txt             # Python dependencies
├── terraform/                   # Infrastructure as code
│   ├── main.tf                 # Main Terraform configuration with integrated Karpenter
│   ├── variables.tf            # Variable definitions
│   ├── outputs.tf              # Output definitions
│   └── userdata.sh             # EC2 user data script for Karpenter nodes
├── k8s/                        # Kubernetes manifests
│   ├── namespace.yaml          # Namespace definition
│   ├── deployment.yaml         # Application deployment
│   ├── service.yaml            # Service definition
│   └── configmap.yaml          # Configuration map
├── scripts/                    # Deployment scripts
│   ├── deploy.sh               # Main deployment script
│   ├── terraform-init.sh       # Terraform initialization
│   └── test-deployment.sh      # Complete deployment test
├── claude-desktop-config.json  # Claude Desktop MCP configuration
├── integrate-with-claude.md     # Claude Desktop integration guide
└── Makefile                    # Build automation

MCP 服务功能

服务（server-simple.py）

• 真实 Kubernetes API 集成：通过正确的 RBAC 连接到实际的 EKS 集群
• HTTP REST API：提供简单的 HTTP 端点，便于测试和集成
• 端点：
  • GET /health - 健康检查，显示 Kubernetes API 连接状态
  • GET /cluster-info - 实时集群信息和命名空间数量
  • GET /nodes - 实时节点状态和信息
  • GET /pods?namespace=<ns> - 获取任意命名空间中的实时 Pod 信息
  • GET /deployments?namespace=<ns> - 部署状态和副本数量
• 安全性：使用 RBAC，并仅授予必要的最小权限
• 错误处理：优雅地处理 API 错误，并返回详细的错误信息
• 负载均衡器：通过 AWS Application Load Balancer 提供外部访问

什么是 MCP（Model Context Protocol）？

MCP 让 Claude 等 AI 助手能够连接到外部数据源和工具。无需运行 kubectl 命令，你就可以用自然语言询问有关集群的问题！

**神奇之处：**你的 EKS 集群 ↔️ MCP 服务 ↔️ Claude Desktop ↔️ 自然语言

自然语言示例

你可以向 Claude 提问，而不必运行 kubectl get nodes 之类的命令：

• “我的集群运行状况如何？” → 获取健康状况、节点和状态
• “我的 MCP 服务 Pod 正在运行吗？” → 检查 Pod 健康状况和重启情况
• “我有哪些 Karpenter 节点？” → 显示自动扩缩的节点
• “列出我的所有命名空间” → 列出集群命名空间
• “我的集群有问题吗？” → 全面的健康检查

演示自然语言界面

# See what natural language queries would look like
python3 demo-natural-language.py

客户端集成选项

1. HTTP REST API：通过 HTTP 直接访问，便于测试和集成
2. Claude Desktop：通过 MCP bridge 提供自然语言界面（参见 claude-desktop-config.json）
3. 负载均衡器：通过 AWS ELB 提供外部访问，适用于生产环境

部署命令

基于 Karpenter 的部署（推荐）

# Deploy everything with Karpenter
./scripts/deploy.sh all

# Or deploy in phases for more control
./scripts/deploy.sh infrastructure  # Phase 1: EKS cluster with minimal nodes
./scripts/deploy.sh karpenter       # Phase 2: Karpenter installation
./scripts/deploy.sh app             # Phase 3: MCP server application

# Test deployment
./scripts/test-deployment.sh

旧版基础设施部署

# Initialize and deploy infrastructure (without Karpenter)
make init plan apply

# Build and deploy application
make deploy

# Complete deployment (infrastructure + app)
make full-deploy

本地测试

# Install dependencies
pip install -r requirements.txt

# Test server locally (requires kubectl access to EKS)
python server-enhanced.py

# Run client example
python client-example.py

Claude Desktop 集成

# Follow the integration guide
cat integrate-with-claude.md

# Copy configuration (macOS example)
cp claude-desktop-config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

配置

环境变量：

• AWS_REGION：AWS 区域（默认值：us-east-1）
• CLUSTER_NAME：EKS 集群名称（默认值：mcp-eks-cluster）
• IMAGE_TAG：Docker 镜像标签（默认值：latest）
• AWS_ACCOUNT_ID：你的 AWS 账户 ID

Karpenter 配置

Karpenter 设置遵循 AWS EKS Blueprints 模式，包含：

• EKS 模块集成：使用内置 Karpenter 支持的 terraform-aws-modules/eks
• 托管节点组：包含 2 个带有 karpenter.sh/controller 污点的 t3.medium 节点，用于运行系统 Pod
• Pod Identity：使用 EKS Pod Identity 安全访问 AWS API
• NodePool：配置实例类型（t3.medium/large/xlarge）和容量类型（spot/on-demand）
• EC2NodeClass：使用发现标签定义 AMI 系列（AL2023）、安全组和子网
• 自动扩缩：节点根据 Pod 调度需求扩缩，合并间隔为 30s
• 成本优化：优先使用 spot 实例，并合并利用率不足的节点

当前状态 ✅

• Karpenter：已成功部署并正在配置节点（AL2023 AMI）
• MCP 服务：HTTP REST API 正在由 Karpenter 管理的节点上运行
• 负载均衡器：已配置外部访问且运行正常
• RBAC：具备访问 Kubernetes API 的适当权限

监控

访问你的 MCP 服务：

kubectl get service mcp-server-service -n mcp-server

查看日志：

kubectl logs -f deployment/mcp-server -n mcp-server

使用示例

HTTP REST API

通过 HTTP 端点直接访问服务：

# Get LoadBalancer URL
LB_URL=$(kubectl get service mcp-server-service -n mcp-server -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')

# Health check
curl http://$LB_URL/health

# Cluster information
curl http://$LB_URL/cluster-info

# Node information
curl http://$LB_URL/nodes

# Pod information
curl http://$LB_URL/pods?namespace=mcp-server

# Deployment information
curl http://$LB_URL/deployments?namespace=default

本地测试

# Port forward for local access
kubectl port-forward -n mcp-server service/mcp-server-service 8080:80

# Test endpoints
curl http://localhost:8080/health
curl http://localhost:8080/cluster-info

测试

快速测试

运行全面的测试套件：

./test-all.sh

手动测试

# Get LoadBalancer URL
LB_URL=$(kubectl get service mcp-server-service -n mcp-server -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')

# Test all endpoints
curl http://$LB_URL/health
curl http://$LB_URL/cluster-info  
curl http://$LB_URL/nodes
curl http://$LB_URL/pods?namespace=mcp-server
curl http://$LB_URL/deployments?namespace=default

测试 Karpenter 自动扩缩容

# Apply test workload to trigger node provisioning
kubectl apply -f test-karpenter.yaml

# Watch Karpenter create new nodes
kubectl get nodeclaim -w

# Scale up to test more provisioning
kubectl scale deployment test-workload --replicas=8

# Check new nodes
kubectl get nodes -l karpenter.sh/nodepool

# Clean up
kubectl delete -f test-karpenter.yaml

监控 Karpenter

# Check Karpenter status
kubectl get nodepool,ec2nodeclass -o wide

# Watch Karpenter logs
kubectl logs -f -n karpenter -l app.kubernetes.io/name=karpenter

# Check node provisioning
kubectl get nodeclaim

故障排除

常见问题

1. 导入错误：使用 pip install -r requirements.txt 安装依赖项
2. Kubernetes API 访问：确保 kubectl 已配置且运行正常
3. ECR 权限：确认 AWS 凭证具有 ECR 访问权限
4. Claude Desktop 连接：检查配置文件路径和格式

日志和调试

# Check pod logs
kubectl logs -f deployment/mcp-server -n mcp-server

# Test Kubernetes connectivity
kubectl get nodes

# Verify ECR repository
aws ecr describe-repositories --repository-names mcp-server

清理

清理 Karpenter 部署

# Remove in reverse order
kubectl delete -f k8s/
cd terraform && terraform destroy -auto-approve

清理旧版部署

make destroy