AI导哈

Kubernetes集群管理服务器

一个基于Model Context Protocol (MCP)的服务器，提供Kubernetes集群管理和信息收集功能，支持通过自然语言交互操作kubectl命令和Kubernetes Python客户端。

  • by aadarshjain
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 aadarshjain/kubectl-mcp-server

使用说明

Kubectl MCP服务器

一个模型上下文协议（MCP）服务器，用于使用kubectl命令和Kubernetes Python客户端进行Kubernetes集群管理和信息收集。

目录

概述

此MCP服务器在LLM（如Claude）和Kubernetes集群之间提供无缝接口。它实现了与Kubernetes资源的自然语言交互，而无需手动运行kubectl命令或编写复杂的API调用。服务器支持只读操作以安全收集信息，并在需要时执行完整的kubectl命令。

项目结构

kubectl-mcp-server/
├── README.md                  # Project documentation
├── requirements.txt           # Python dependencies
├── .env                       # Environment configuration file (create from .env.example)
├── .env.example               # Example environment configuration
└── server.py                  # Main server application with FastMCP setup

特性

  • 群集管理：列出并在不同的Kubernetes上下文之间切换
  • 只读操作：用于信息收集的安全kubectl命令（get、describes、explain）
  • 完全支持kubectl：需要时执行任何kubectl命令
  • Kubernetes API集成：通过Python客户端直接访问Kubernetes API
  • 上下文切换：在不同集群上下文之间无缝切换
  • 安全控制：内置保护，以只读模式防止破坏性操作

安装

先决条件

对于本地开发和测试，您需要：

系统要求

  • Python 3.8+ -MCP服务器是用Python构建的
  • kubectl -Kubernetes命令行工具已安装并配置
  • Kubernetes集群访问 -具有集群凭据的有效kubeconfig

可选（用于Claude Desktop集成）

  • 克劳德桌面 已安装应用程序
  • Node.js和npm （如果将npx用于mcp远程）

设置

  1. 克隆并导航到项目：

    git clone <repository-url>
cd kubectl-mcp-server

  2. 安装依赖项：

    pip install -r requirements.txt

  3. 配置环境变量：

    cp .env.example .env
# Edit .env file to set your kubeconfig path if different from default

  4. 确保kubectl已安装并配置：

    kubectl version --client
kubectl config get-contexts

运行服务器

基本用法

# Run with defaults
python server.py

# Run with debug logging
python server.py --log-level debug

可用工具

1. list_clusters()

从kubeconfig文件中列出所有可用的Kubernetes集群。

退货：

  • 包含名称和群集信息的可用群集列表
  • 当前活动上下文

例子：

{
  "clusters": [
    {"name": "prod-cluster", "cluster": "prod-k8s"},
    {"name": "dev-cluster", "cluster": "dev-k8s"}
  ],
  "active_context": "prod-cluster"
}

2. get_current_context()

获取MCP服务器和系统正在使用的当前Kubernetes上下文。

退货：

  • 存储在MCP服务器中的当前上下文
  • 系统当前的kubectl上下文

例子：

{
  "current_context": "prod-cluster",
  "system_context": "prod-cluster"
}

3. switch_context(context: str)

切换到不同的Kubernetes上下文。

参数：

  • context （string）：要切换到的上下文的名称

退货：

  • 成功消息或错误详细信息

例子：

switch_context("dev-cluster")
# Returns: {"message": "Switched to context: dev-cluster"}

4. run_kubectl_command_ro(command: str)

安全地执行只读kubectl命令。

参数：

  • command （string）：kubectl命令，以“kubectl”开头

允许的操作：

  • get -检索资源
  • describe -显示详细的资源信息
  • explain -显示资源文档
  • config view -查看kubeconfig
  • config get-contexts -列出可用上下文
  • version -显示kubectl/集群版本
  • api-resources -列出可用的API资源
  • cluster-info -显示集群信息

退货：

  • 命令输出或错误消息

例子：

run_kubectl_command_ro("kubectl get pods -n default")

5. run_kubectl_command(command: str)

执行任何kubectl命令（小心使用）。

参数：

  • command （string）：kubectl命令，以“kubectl”开头

退货：

  • 命令输出或错误消息

警告： 此工具可以执行破坏性操作。使用 run_kubectl_command_ro() 为了安全地收集信息。

配置

环境变量

服务器使用环境变量进行配置，可以在 .env 文件：

# Path to the kubeconfig file
# Use full path for reliability, e.g., /Users/yourusername/.kube/config
# If not set, defaults to ~/.kube/config
KUBECONFIG_PATH=/Users/yourusername/.kube/config

# Log level for the server
LOG_LEVEL=INFO

Kubeconfig设置

确保你的kubeconfig配置正确：

# Check current context
kubectl config current-context

# List all contexts
kubectl config get-contexts

# Set default context
kubectl config use-context <context-name>

服务器将自动从以下位置加载：

  1. 中指定的路径 KUBECONFIG_PATH 环境变量
  2. 这 KUBECONFIG 环境变量
  3. 默认位置(~/.kube/config)

Claude桌面配置

要与Claude Desktop集成，请将此配置添加到您的Claude Desktop配置文件中：

{
  "mcpServers": {
    "kubectl-mcp-server": {
      "command": "/full/path/to/python",
      "args": ["/path/to/kubectl-mcp-server/server.py"]
    }
  }
}

配置文件位置：

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • 视窗: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

安全

只读模式

这 run_kubectl_command_ro() 该工具通过以下方式提供安全访问：

  • 仅允许信息收集命令
  • 阻止破坏性操作（删除、更新、修补等）
  • 防止资源修改

访问控制

  • 服务器从kubeconfig继承权限
  • 无需额外的身份验证层（依赖于Kubernetes RBAC）
  • 命令的执行权限与kubectl设置相同

最佳实践

  • 使用 run_kubectl_command_ro() 用于一般查询
  • 预留 run_kubectl_command() 仅适用于受信任的操作
  • 定期审核您的kubeconfig权限
  • 考虑使用权限有限的专用服务帐户

示例用法

集群基本信息

User: What clusters do I have access to?
Claude: [Uses list_clusters() to show available contexts]

User: Switch to the development cluster
Claude: [Uses switch_context("dev-cluster")]

User: Show me all pods in the default namespace
Claude: [Uses run_kubectl_command_ro("kubectl get pods -n default")]

资源检查

User: Describe the nginx deployment
Claude: [Uses run_kubectl_command_ro("kubectl describe deployment nginx")]

User: What's the current cluster version?
Claude: [Uses run_kubectl_command_ro("kubectl version")]

User: Show me all namespaces
Claude: [Uses run_kubectl_command_ro("kubectl get namespaces")]

高级操作

User: Scale the nginx deployment to 3 replicas
Claude: [Uses run_kubectl_command("kubectl scale deployment nginx --replicas=3")]

故障排除

常见问题

连接问题：

  • 验证kubectl连接： kubectl cluster-info
  • 检查kubeconfig： kubectl config view
  • 确保对集群进行正确的身份验证

权限错误：

  • 检查集群中的RBAC权限
  • 验证服务帐户是否具有必要的权限
  • 查看kubeconfig用户凭据

上下文切换问题：

  • 列出可用上下文： kubectl config get-contexts
  • 验证上下文名称是否完全匹配
  • 检查kubeconfig中是否存在上下文

导入错误：

  • 安装所需的依赖项： pip install -r requirements.txt
  • 验证Python版本兼容性（3.8+）
  • 检查kubectl安装： kubectl version --client

相关 MCP