K8s MCP Server

🚀 Kubernetes MCP Server

A flexible Machine Communication Protocol (MCP) server that provides an interface with Kubernetes and supports multiple functions.

🚀 Quick Start

The Kubernetes MCP Server is a versatile tool designed to work seamlessly with Kubernetes environments. It offers a range of features to enhance your experience, from automatic parameter detection to multi - environment compatibility.

✨ Features

• Automatic Detection of Extension Script Parameters: The system automatically identifies and parses script parameters without manual configuration.
• Pydantic Model Support: Utilize Pydantic for data validation and serialization to ensure correct data structures.
• Multi - Environment Compatibility: Supports different Kubernetes environment configurations.
• Highly Scalable: Facilitates the integration of new functional modules and protocols.

📦 Installation

Prerequisites

• Operating System: Linux or macOS (Windows can run via WSL).
• Python Version: 3.8+
• kubectl installed and configured in the system path.

Installation Steps

1. Clone the code from the project repository:

   git clone https://github.com/your-repository/kubernetes-mcp.git
   cd kubernetes-mcp
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Start the MCP server:

   python3 bin/start_mcp_server.py
   

💻 Usage Examples

Basic Usage

# Run the MCP server, listening on localhost:50051 by default
python3 bin/k8s-mcp-server run

# Run in debug mode
DEBUG=1 python3 bin/k8s-mcp-server run

# Specify the configuration file path
CONFIG_PATH=/path/to/config.yaml python3 bin/k8s-mcp-server run

Custom Script Usage

from kubernetes_mcp_sdk import KubernetesMCPClient

client = KubernetesMCPClient()
response = client.invoke_command(
    command_name="your_command",
    parameters={
        "param1": "value1",
        "param2": 123
    }
)
print(response)

📚 Documentation

Directory Structure

The project root directory should contain the following folders:

kubernetes-mcp/
├── bin/                 # Store executable scripts, such as startup scripts
├── config/             # Project configuration files, including MCP server configuration
├── scripts/            # Location for custom extension scripts, default is scripts/
└── src/                # Core source code directory, containing various functional modules

Creating Custom Scripts

Script Template

#!/usr/bin/env python3
"""
Example script name

Briefly describe the function of the script.

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():
    """
    The main function of the script, responsible for parsing parameters and executing logic
    
    Returns:
        dict: Execution result
    """
    parser = argparse.ArgumentParser(
        description="Detailed description of the script function",
        formatter_class=argparse.ArgumentDefaultsHelpFormatter
    )
    
    # Define parameters
    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"
    )
    
    # Handle the --args-file parameter
    parser.add_argument("--args-file", help="Path to the JSON file containing parameters")
    args, _ = parser.parse_known_args()
    
    if args.args_file:
        with open(args.args_file, 'r') as f:
            arguments = json.load(f)
        for arg_name, arg_value in arguments.items():
            setattr(args, arg_name, arg_value)
    else:
        args = parser.parse_args()
    
    # Use parameters
    print(f"Parameter 1: {args.param1}")
    print(f"Parameter 2: {args.param2}")
    
    # Add custom logic

if __name__ == "__main__":
    main()

Environment Variables

• SCRIPTS_DIR: Override the default script directory location.

  SCRIPTS_DIR=/path/to/scripts python3 bin/k8s-mcp-server run
  

Architecture Composition

1. MCP Server: Implements the MCP protocol using the FastMCP SDK.
2. Kubernetes Client: Responsible for interacting with kubectl.
3. Extension Scripts: Provide specialized functions with automatic parameter detection.

Pydantic Model Application

• Data validation and serialization.
• Type - safe data models.
• Improved IDE support and error detection capabilities.

🔧 Technical Details

The server uses the FastMCP SDK to implement the MCP protocol, ensuring efficient communication. The integration with Kubernetes is achieved through the kubectl client, allowing seamless interaction with the Kubernetes cluster. The use of Pydantic models enhances data integrity and development efficiency.

🤝 Contribution Guidelines

Contributions are welcome! Please submit code or raise issues through GitHub.

📄 License

This project is licensed under the MIT License.

📞 Contact

If you need assistance, please contact the maintainers.