MCP Server on EKS

EKS 上の MCP サーバー

このプロジェクトでは、インフラストラクチャ管理に Terraform を使用して、Amazon EKS 上に Model Context Protocol（MCP）サーバーをデプロイします。

アーキテクチャ

• MCP サーバー：MCP プロトコルを実装した Python ベースのサーバー
• コンテナ：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 ↔️ 自然言語

自然言語での質問例

kubectl get nodes のようなコマンドの代わりに、Claude に次のように尋ねることができます。

• 「クラスターの状態はどうですか？」 → ヘルス状態、ノード、ステータスを取得します
• 「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 ブリッジを介した自然言語インターフェース（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 を使用します
• マネージドノードグループ：システム Pod 用に karpenter.sh/controller taint を設定した 2 台の t3.medium ノード
• Pod Identity：安全な AWS API アクセスに EKS Pod Identity を使用します
• NodePool：インスタンスタイプ（t3.medium/large/xlarge）とキャパシティタイプ（spot/on-demand）を設定します
• EC2NodeClass：検出タグを使用して AMI ファミリー（AL2023）、セキュリティグループ、サブネットを定義します
• オートスケーリング：Pod のスケジューリング要件に応じてノードをスケーリングし、30 秒ごとに集約します
• コストの最適化：スポットインスタンスを優先し、利用率の低いノードを集約します

現在のステータス ✅

• Karpenter：デプロイに成功し、ノードをプロビジョニングしています（AL2023 AMI）
• MCP Server：Karpenter が管理するノード上で HTTP REST API を実行しています
• ロードバランサー：外部アクセスを設定済みで、正常に動作しています
• 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