K8s Mcp Server

Kubernetes & Helm MCP サーバー

Kubernetes および Helm 環境の管理用に設計された、n8n との連携をサポートするシンプルで信頼性の高い MCP（Model Context Protocol）サーバーです。

機能

• n8n ネイティブサポート - n8n MCP Client ノードを完全にサポートします
• SSE 接続 - リアルタイムの双方向通信に Server-Sent Events を使用します
• Kubernetes 連携 - kubectl ツールへの包括的なアクセスを提供します
• Helm サポート - Helm チャートおよびリリースの管理機能を提供します
• モジュール式アーキテクチャ - エントリーポイントとサーバー実装を明確に分離します

ファイル構成

k8s-mcp-server/
├── src/                           # Source code directory
│   ├── index.js                   # Main program entry, handles lifecycle and parameter parsing
│   ├── server.js                  # MCP + Express integration, server implementation
│   ├── tools/                     # Tool modules
│   │   ├── base-tool.js           # Base tool class
│   │   ├── kubectl-get.js         # Resource query tool (supports label filtering)
│   │   ├── kubectl-logs.js        # Pod log viewing tool
│   │   ├── kubectl-describe.js    # Resource detailed description tool
│   │   ├── kubectl-cluster-info.js # Cluster information query tool
│   │   ├── kubectl-get-yaml.js    # Resource YAML format output tool
│   │   ├── kubectl-top-nodes.js   # Node resource usage monitoring
│   │   ├── kubectl-top-pods.js    # Pod resource usage monitoring
│   │   ├── kubectl-top-containers.js # Container resource usage monitoring
│   │   ├── kubectl-scale-deployment.js # Deployment scaling tool
│   │   ├── kubectl-restart-deployment.js # Deployment restart tool
│   │   ├── kubectl-edit-hpa.js    # HPA editing tool
│   │   ├── helm-list.js           # Helm release list tool
│   │   ├── helm-status.js         # Helm release status tool
│   │   ├── helm-repo-list.js      # Helm repository list tool
│   │   ├── helm-get-values.js     # Helm release configuration values tool
│   │   └── helm-history.js        # Helm release history tool
│   └── utils/                     # Utility functions
│       ├── logger.js              # Logging system
│       ├── validator.js           # Input validation (including label validation)
│       ├── kubectl.js             # kubectl execution tool
│       └── helm.js                # helm execution tool
├── package.json                   # Project configuration and dependencies
├── package-lock.json              # Dependency lock file
├── Dockerfile                     # Docker container build file
├── build.sh                       # Docker build script
├── .gitignore                     # Git ignore file configuration
├── .cursorignore                  # Cursor editor ignore file configuration
└── README.md                      # Project documentation

アーキテクチャの説明

• src/index.js - メインプログラムのエントリーで、以下を担当します。

  • コマンドラインパラメーターの解析
  • 環境変数の設定
  • ライフサイクル管理
  • グレースフルシャットダウンの処理
  • エラー処理

• src/server.js - サーバーの実装で、以下を担当します。

  • MCP サーバーの設定とツールの登録
  • Express アプリケーションの作成（SSE モード）
  • MCP メッセージの処理
  • SSE 接続の管理

クイックスタート

ローカル開発

1. 依存関係をインストール

npm install

2. SSE モードを起動（n8n 用）

npm run start:http
# Or specify port
npm run start:http -- --port 3001

3. サービスの状態を確認

curl http://localhost:3001/health

Docker でのデプロイ

1. イメージをビルド

docker build -t k8s-mcp-server .

2. コンテナーを起動（kubeconfig のマウントが必要）

⚠️ 重要： コンテナーの起動時に、MCP サーバーが Kubernetes クラスターにアクセスできるよう、ローカルの .kube/config をコンテナー内の /home/nodejs/.kube/config パスにマウントする必要があります。

# Use local kubeconfig
docker run -p 3001:3000 \
  -v ~/.kube/config:/home/nodejs/.kube/config:ro \
  k8s-mcp-server

3. kubeconfig のパスをカスタマイズ

# Use custom kubeconfig file
docker run -p 3001:3000 \
  -v /path/to/your/kubeconfig:/home/nodejs/.kube/config:ro \
  k8s-mcp-server

4. サービスアカウントトークンを使用（Kubernetes 内部でのデプロイ）

# When deploying inside a Kubernetes cluster, you can use service account
docker run -p 3001:3000 \
  -v /var/run/secrets/kubernetes.io/serviceaccount:/var/run/secrets/kubernetes.io/serviceaccount:ro \
  -e KUBERNETES_SERVICE_HOST \
  -e KUBERNETES_SERVICE_PORT \
  k8s-mcp-server

5. 接続を確認

コンテナーの起動後、Kubernetes への接続状態を確認できます。

# Check service status
curl http://localhost:3001/health

# Test Kubernetes connection
curl -X POST http://localhost:3001/messages \
  -H "Content-Type: application/json" \
  -d '{
    "method": "tools/call",
    "params": {
      "name": "kubectl_get",
      "arguments": {"resource": "nodes"}
    }
  }'

6. 重要な注意事項

権限要件：

• kubeconfig ファイルに、Kubernetes クラスターへの適切なアクセス権限があることを確認してください
• セキュリティ向上のため、読み取り専用のサービスアカウントを使用することをおすすめします
• コンテナーは nodejs ユーザーとして実行されます。マウントしたファイルに適切な読み取り権限があることを確認してください

トラブルシューティング：

# Check kubeconfig file permissions
ls -la ~/.kube/config

# Verify kubeconfig validity
kubectl --kubeconfig ~/.kube/config get nodes

# Check kubeconfig inside container
docker exec -it <container-id> cat /home/nodejs/.kube/config

Docker Compose の例：

version: '3.8'
services:
  k8s-mcp-server:
    build: .
    ports:
      - "3001:3000"
    volumes:
      - ~/.kube/config:/home/nodejs/.kube/config:ro
    environment:
      - NODE_ENV=production
    restart: unless-stopped

n8n での使用

ステップ 1：MCP サーバーを起動

MCP サーバーが SSE モードで実行されていることを確認してください。

cd k8s-mcp/k8s-mcp-server
npm run start:http -- --port 3001

サーバーの起動後、次のように表示されます。

MCP Server started at http://localhost:3001
SSE endpoint: http://localhost:3001/sse (n8n connects here)
Message endpoint: http://localhost:3001/messages
Health check: http://localhost:3001/health
SSE mode - designed for n8n