Kubernetes MCP Server

Kubernetes MCP サーバー

カスタム拡張スクリプトをサポートする、柔軟な Machine Communication Protocol（MCP）サーバーです。Kubernetes の管理機能を提供します。

機能

• 公式 MCP SDK を使用して Model Context Protocol（MCP）を実装しています
• 表形式の出力で、幅広い Kubernetes 管理操作を提供します
• カスタム拡張スクリプトの動的な読み込みと自動検出をサポートします
• スクリプトのパラメーターを自動検出し、検証します
• 型安全性を実現する Pydantic モデルを使用した、クリーンでモジュール化されたアーキテクチャです

ディレクトリ構成

• bin/：主な実行可能コンポーネントが含まれます

  • k8s_mcp_wrapper.py：MCP サーバーのメイン実行ファイル

• scripts/：MCP サーバーのプラグインスクリプトが含まれます

  • 機能を拡張するには、カスタムスクリプトをここに追加します

前提条件

• Python 3.10 以降（MCP SDK に必要）
• kubectl がインストールされ、設定されていること
• 必要な Python パッケージ（requirements.txt を参照）

インストール

pip を使用する場合

1. このリポジトリをクローンします：

   git clone https://github.com/yourusername/k8s-mcp-server.git
   cd k8s-mcp-server
   

2. （任意）仮想環境を作成します：

   python3.10 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. 依存関係をインストールします：

   pip install -r requirements.txt
   

uv を使用する場合（インストールが高速）

1. まだインストールされていない場合は、uv をインストールします：

   pip install uv
   

2. リポジトリをクローンします：

   git clone https://github.com/yourusername/k8s-mcp-server.git
   cd k8s-mcp-server
   

3. uv を使用して仮想環境を作成し、依存関係をインストールします：

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv pip install -r requirements.txt
   

使用方法

MCP サーバーの実行

bin ディレクトリから MCP サーバーを実行します：

cd bin
python3 k8s_mcp_wrapper.py

ウェブサーバーを使用した開発モードで実行する場合（デバッグに便利です）：

cd bin
python3 k8s_mcp_wrapper.py --dev --dev-port 8000

サーバーは次の処理を行います：

1. kubectl が利用可能かどうかを確認します
2. scripts/ ディレクトリ内のスクリプトを検出して登録します
3. MCP プロトコルのコマンドの待ち受けを開始します

利用可能なツール

MCP サーバーには、次の組み込みツールが用意されています：

ツール名	説明
get_pods	指定した名前空間内の Pod の一覧を取得します
get_services	指定した名前空間内の Service の一覧を取得します
get_deployments	指定した名前空間内の Deployment の一覧を取得します
get_namespaces	クラスター内のすべての名前空間の一覧を取得します
describe_resource	Kubernetes リソースの詳細を表示します
get_pod_logs	指定した名前空間内の Pod のログを取得します
create_namespace	Kubernetes クラスターに新しい名前空間を作成します
delete_resource	Kubernetes リソースを削除します
scale_deployment	Deployment のレプリカ数を指定した数に変更します
get_events	Kubernetes クラスターのイベントを取得します
get_current_context	現在の kubectl コンテキストを取得します
get_available_contexts	利用可能な kubectl コンテキストの一覧を取得します
switch_context	kubectl コンテキストを切り替えます
list_scripts	利用可能なすべてのスクリプトとそのパラメーターを一覧表示します

また、scripts/ ディレクトリ内のすべてのスクリプトは、script_ というプレフィックスを付けてツールとして自動登録されます。

カスタムスクリプトの作成

scripts/ ディレクトリにカスタムスクリプトを追加して、MCP サーバーの機能を拡張できます。

スクリプトの要件

1. スクリプトは .py 拡張子を持つ Python ファイルである必要があります
2. パラメーターの定義には argparse を使用してください（自動検出されます）
3. --args-file フラグを指定した JSON ファイルから引数を受け取れるようにしてください

スクリプトの検出精度を向上させる

MCP サーバーがスクリプトを正しく検出できない場合は、次の改善をお試しください：

1. パラメーターの説明を含む、詳細なモジュールレベルの docstring を追加します：

   """
   My Script Name
   
   Description of what this script does.
   
   Parameters:
       --param1: Description of parameter 1 (required)
       --param2: Description of parameter 2 (default: default_value)
   """
   

2. docstring に対応する、詳細な argparse のヘルプテキストを使用します：

   parser.add_argument(
       "--param1",
       type=str,
       required=True,
       help="Description of parameter 1 (required)"
   )
   

3. ArgumentDefaultsHelpFormatter を使用して、ヘルプテキストにデフォルト値を含めます：

   parser = argparse.ArgumentParser(
       description="Description of the script",
       formatter_class=argparse.ArgumentDefaultsHelpFormatter
   )
   

4. 適切な権限を設定して、スクリプトを実行可能にします：

   chmod +x scripts/your_script.py
   

スクリプトのテンプレート

新しいスクリプトを作成するための基本的なテンプレートを以下に示します：

#!/usr/bin/env python3
"""
Script Name

Brief description of what the script does.

Parameters:
    --param1: Description of parameter 1 (required)
    --param2: Description of parameter 2 (default: default_value)
"""

import argparse
import json
import sys
import os

def main():
    """
    Main function that parses arguments and executes the script.
    
    This function demonstrates how to properly structure a script 
    for the Kubernetes MCP Server with clear parameter definitions.
    
    Returns:
        dict: A dictionary with the execution results
    """
    parser = argparse.ArgumentParser(
        description="Description of the script",
        formatter_class=argparse.ArgumentDefaultsHelpFormatter
    )
    
    # Define your parameters with detailed docstrings
    parser.add_argument(
        "--param1", 
        type=str, 
        required=True, 
        help="Description of parameter 1 (required)"
    )
    
    parser.add_argument(
        "--param2", 
        type=int,
        default=42, 
        help="Description of parameter 2"
    )
    
    # Check if the --args-file flag is present
    parser.add_argument("--args-file", help="JSON file containing arguments")
    args, _ = parser.parse_known_args()
    
    if args.args_file:
        # Load arguments from the file
        with open(args.args_file, 'r') as f:
            arguments = json.load(f)
            
        # Convert the loaded JSON arguments into a namespace
        for arg_name, arg_value in arguments.items():
            setattr(args, arg_name, arg_value)
    else:
        # Parse all arguments normally for CLI usage
        args = parser.parse_args()
    
    # Use your arguments here
    print(f"Parameter 1: {args.param1}")
    print(f"Parameter 2: {args.param2}")
    
    # Implement your script logic here
    
if __name__ == "__main__":
    main()

環境変数

• SCRIPTS_DIR：デフォルトのスクリプトディレクトリの場所を上書きします

  SCRIPTS_DIR=/path/to/scripts python3 bin/k8s_mcp_wrapper.py
  

アーキテクチャ

システムは以下のコンポーネントで構成されています。

1. MCP サーバー：FastMCP SDK を使用して MCP プロトコルを実装します
2. Kubernetes クライアント：Pydantic モデルを使用して kubectl と直接やり取りします
3. 拡張スクリプト：自動検出されたパラメーターを使用して、特化した機能を提供します

Pydantic モデル

システムでは、以下の目的で Pydantic を使用しています。

• Kubernetes リソース用の型安全なモデル
• データ構造の自動検証
• IDE との連携の向上とエラー検出

貢献

貢献を歓迎します！お気軽に Pull Request を送信してください。

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。