wakeupworld/k8s_mcp_server

Kubernetes MCP Server

A flexible Machine Communication Protocol (MCP) server that provides Kubernetes management capabilities with support for custom extension scripts.

Features

• Implements the Model Context Protocol (MCP) using the official MCP SDK
• Provides a wide range of Kubernetes management operations through tabular output
• Supports dynamic loading and auto-detection of custom extension scripts
• Automatic script parameter detection and validation
• Clean, modular architecture with Pydantic models for type safety

Directory Structure

• bin/: Contains main executable components

  • k8s_mcp_wrapper.py: The main MCP server executable

• scripts/: Contains plugin scripts for the MCP server

  • Add your custom scripts here to extend functionality

Prerequisites

• Python 3.10 or higher (required by MCP SDK)
• kubectl installed and configured
• Required Python packages (see requirements.txt)

Installation

Using pip

1. Clone this repository:

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

2. (Optional) Create a virtual environment:

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

3. Install dependencies:

   pip install -r requirements.txt
   

Using uv (faster installation)

1. Install uv if not already installed:

   pip install uv
   

2. Clone the repository:

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

3. Create a virtual environment and install dependencies using uv:

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

Usage

Running the MCP Server

Execute the MCP server from the bin directory:

cd bin
python3 k8s_mcp_wrapper.py

For development mode with web server (useful for debugging):

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

The server will:

1. Check if kubectl is available
2. Discover and register scripts from the scripts/ directory
3. Start listening for MCP protocol commands

Available Tools

The MCP server provides the following built-in tools:

Additionally, all scripts in the scripts/ directory are automatically registered as tools with the prefix script_.

Creating Custom Scripts

You can extend the MCP server's functionality by adding custom scripts to the scripts/ directory.

Script Requirements

1. Scripts must be Python files with a .py extension
2. Scripts should use argparse for parameter definitions (they will be auto-detected)
3. Scripts should support receiving arguments via a JSON file with the --args-file flag

Improving Script Detection

If your scripts aren't being properly detected by the MCP server, try these improvements:

1. Add detailed docstrings at the module level with parameter descriptions:

   """
   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. Use detailed argparse help texts that match your docstrings:

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

3. Use ArgumentDefaultsHelpFormatter to include default values in help texts:

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

4. Make your script executable with proper permissions:

   chmod +x scripts/your_script.py
   

Script Template

Here's a basic template for creating a new script:

#!/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()

Environment Variables

• SCRIPTS_DIR: Override the default scripts directory location

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

Architecture

The system consists of the following components:

1. MCP Server: Uses the FastMCP SDK to implement the MCP protocol
2. Kubernetes Client: Handles direct interactions with kubectl using Pydantic models
3. Extension Scripts: Provide specialized functionality with auto-detected parameters

Pydantic Models

The system uses Pydantic for:

• Type-safe models for Kubernetes resources
• Automatic validation of data structures
• Better IDE integration and error detection

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.