Kubernetes MCP Server

Kubernetes MCP 服务

一个灵活的机器通信协议（MCP）服务，提供 Kubernetes 管理功能，并支持自定义扩展脚本。

功能

• 使用官方 MCP SDK 实现模型上下文协议（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

使用 Web 服务以开发模式运行（便于调试）：

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

服务将会：

1. 检查 kubectl 是否可用
2. 从 scripts/ 目录发现并注册脚本
3. 开始监听 MCP 协议命令

可用工具

MCP 服务提供以下内置工具：

工具名称	描述
get_pods	获取指定命名空间中的 Pod 列表
get_services	获取指定命名空间中的服务列表
get_deployments	获取指定命名空间中的部署列表
get_namespaces	获取集群中所有命名空间的列表
describe_resource	详细描述 Kubernetes 资源
get_pod_logs	获取指定命名空间中某个 Pod 的日志
create_namespace	在 Kubernetes 集群中创建新的命名空间
delete_resource	删除 Kubernetes 资源
scale_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. 在模块级别添加详细的文档字符串，说明参数：

   """
   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. 使用与文档字符串相符的详细 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 文件。