使用说明

项目简介

Claude Kubernetes MCP Server 是一个使用 Go 语言构建的 Model Context Protocol (MCP) 服务器，旨在为大型语言模型（LLM）客户端提供 Kubernetes 环境的上下文信息和智能运维能力。它集成了 Kubernetes、ArgoCD、GitLab 和 Claude AI，通过 REST API 提供服务，帮助用户理解和操作 Kubernetes 集群。

主要功能点

Kubernetes 资源信息查询: 提供 Kubernetes 命名空间、资源列表、资源详情和事件查询接口。
ArgoCD 应用集成: 支持 ArgoCD 应用列表和详情查询，方便用户了解 GitOps 应用状态。
GitLab 代码仓库关联: 集成 GitLab 项目信息，方便追溯 Kubernetes 资源变更对应的代码提交和流水线。
Claude AI 智能分析: 利用 Claude AI 的自然语言处理能力，对 Kubernetes 资源进行智能分析和故障排查，并提供建议。
资源上下文构建: 自动收集 Kubernetes 资源及其相关的 ArgoCD 应用、GitLab 项目和事件信息，构建全面的上下文，为 LLM 提供丰富的知识库。
REST API 接口: 提供标准的 RESTful API 接口，方便 MCP 客户端调用和集成。
多种部署方式: 支持本地运行、Docker 容器部署和 Kubernetes Helm Chart 部署。

安装步骤

克隆代码仓库

git clone https://github.com/blankcut/kubernetes-mcp-server.git
cd kubernetes-mcp-server

导出必需的环境变量

根据您的配置，导出 ArgoCD、GitLab 和 Claude API 的凭据：

export ARGOCD_USERNAME="您的Argocd用户名"
export ARGOCD_PASSWORD="您的Argocd密码"
export GITLAB_TOKEN="您的GitLab私人访问令牌"
export CLAUDE_API_KEY="您的Claude API密钥"
export VAULT_TOKEN="（可选，如果使用Vault）"

确保 '~/.kube/config' 文件可用，或者设置 'KUBECONFIG' 环境变量：

export KUBECONFIG=~/.kube/config

配置 'config.yaml' 文件

修改 'kubernetes-claude-mcp/config.yaml' 文件，填入您的凭据和服务器配置。关键配置项包括：

server:
  address: ":8080" # 服务器监听地址和端口
  readTimeout: 30 # 读取超时时间 (秒)
  writeTimeout: 60 # 写入超时时间 (秒)
  auth:
    apiKey: "" # API 密钥，用于客户端鉴权，请设置一个安全的密钥

kubernetes:
  kubeconfig: "" # Kubeconfig 文件路径，留空则使用默认路径 ~/.kube/config
  inCluster: false # 是否在 Kubernetes 集群内部署运行
  defaultContext: "" # 默认 Kubernetes Context
  defaultNamespace: "default" # 默认 Kubernetes 命名空间

argocd:
  url: "http://example.argocd.com" # ArgoCD 服务器 URL
  authToken: "" # ArgoCD 认证 Token (如果使用 Token 认证，优先使用)
  username: "${ARGOCD_USERNAME}" # ArgoCD 用户名 (如果使用用户名密码认证)
  password: "${ARGOCD_PASSWORD}" # ArgoCD 密码 (如果使用用户名密码认证)
  insecure: true # 是否禁用 TLS 证书验证 (测试环境可设置为 true)

gitlab:
  url: "https://gitlab.com" # GitLab 服务器 URL
  authToken: "${GITLAB_TOKEN}" # GitLab 私人访问令牌
  apiVersion: "v4" # GitLab API 版本
  projectPath: "" # GitLab 项目路径 (可选，如果需要限制项目访问范围)

claude:
  apiKey: "${CLAUDE_API_KEY}" # Claude API 密钥
  baseURL: "https://api.anthropic.com" # Claude API Base URL
  modelID: "claude-3-haiku-20240307" # 使用的 Claude 模型 ID
  maxTokens: 4096 # Claude 模型最大 Token 限制
  temperature: 0.7 # Claude 模型 Temperature 参数

请务必设置 'server.auth.apiKey'，用于 MCP 客户端的 API 密钥认证。

服务器配置

MCP 服务器作为后端服务，主要由开发者或运维人员配置和部署。对于 MCP 客户端使用者，主要关注如何与 MCP 服务器建立连接。

MCP 客户端需要配置 MCP 服务器的启动命令 (command) 及其参数 (args) 才能与 MCP 服务器建立连接。但本仓库为标准的 HTTP RESTful API 服务，并非基于 JSON-RPC 协议，因此 MCP 客户端无需配置启动命令和参数。

MCP 客户端通常需要配置 MCP 服务器的访问地址 和 API 密钥 (通过 HTTP Header 'X-API-Key' 传递) 即可与服务器交互。

例如，如果 MCP 服务器部署在 'http://localhost:8080'，API 密钥设置为 'your-api-key'，则 MCP 客户端需要配置这些信息才能访问服务器提供的 API 接口。具体接口请参考 API 文档 部分。

基本使用方法

启动 MCP 服务器

根据您的部署方式（本地运行、Docker 或 Helm），启动 Claude Kubernetes MCP Server。

使用 MCP 客户端或 HTTP 客户端

使用 MCP 客户端工具（如果存在）或任何 HTTP 客户端（如 'curl'、Postman）向 MCP 服务器发送 HTTP 请求。

所有 API 请求都需要在 Header 中包含 'X-API-Key' 字段，值为您在 'config.yaml' 中配置的 'apiKey'。

常用 API 示例 (使用 curl):

健康检查:

curl -X GET http://localhost:8080/api/v1/health

查询 Kubernetes Pod 列表:

curl -X GET http://localhost:8080/api/v1/resources/pod -H "X-API-Key: your-api-key"

智能分析 Kubernetes Pod:

curl -X POST http://localhost:8080/api/v1/mcp/resource -H "Content-Type: application/json" -H "X-API-Key: your-api-key" -d '{
  "resource": "pod",
  "name": "example-pod",
  "namespace": "default",
  "query": "What’s wrong with this pod?"
}'

更多 API 接口和请求参数，请参考 API 文档 部分。

API 文档

请参考仓库 README.md 文件中的 API Documentation 部分，获取详细的 API 接口说明和参数信息。

Postman Collection

Postman Collection (用于快速测试 API 接口) 将在仓库中提供，请关注仓库更新。

关键词