MCP Remote Server for Kubernetes

🚀 通用远程 MCP 服务器 - 基于 MCP (Model Context Protocol) 协议的 Kubernetes 管理服务器，支持通过 HTTP/SSE 协议远程访问，为各种 AI 平台和应用程序提供 Kubernetes 集群的自然语言管理能力。

🌟 核心优势

🔌 通用兼容性: 支持所有遵循 MCP 协议的客户端（Dify、Claude Desktop、自定义客户端等）
🌐 远程访问: 通过 HTTP/SSE 协议提供远程 MCP 服务，无需本地部署
🔒 企业级安全: JWT 认证、RBAC 权限控制、速率限制等安全机制
☸️ 完整 K8s 支持: 涵盖 Pod、Service、Deployment 等资源的完整生命周期管理
📊 生产就绪: 健康检查、结构化日志、错误处理、监控告警等企业特性

🚀 主要特性

MCP 协议支持

标准协议: 完整实现 MCP 2024-11-05 协议规范
多传输方式: 支持 HTTP POST 和 SSE (Server-Sent Events)
实时通信: 支持双向通信和事件推送

Kubernetes 集成

API 代理: 通过代理模式提供完整的 Kubernetes API 访问
资源管理: 支持 Pod、Service、Deployment、ConfigMap 等资源操作
日志查看: 实时获取容器日志
多集群: 支持集群内和集群外两种部署模式

安全和认证

JWT 认证: 基于 JSON Web Token 的安全认证
RBAC 权限: 细粒度的角色权限控制
速率限制: 防止 API 滥用和 DDoS 攻击
安全传输: 支持 HTTPS 和安全头部配置

多平台支持

🤖 Dify: 完整的 Dify 平台集成支持
💬 Claude Desktop: 原生 MCP 客户端支持
🔧 自定义客户端: 提供多语言 SDK 和示例
🌐 Web 应用: 支持浏览器直接访问

📋 系统要求

Node.js >= 18.0.0
Kubernetes 集群访问权限
Docker (可选，用于容器化部署)

🛠️ 安装和配置

1. 克隆项目

git clone <repository-url>
cd mcp-remote-server-kubernetes

2. 安装依赖

npm install

3. 配置环境变量

复制环境变量模板并根据需要修改：

cp .env.example .env

主要配置项：

# 服务器配置
PORT=3000
HOST=0.0.0.0

# Kubernetes 配置
KUBECONFIG=/path/to/your/kubeconfig
K8S_IN_CLUSTER=false
K8S_NAMESPACE=default

# 认证配置
AUTH_ENABLED=true
JWT_SECRET=your-secret-key
JWT_EXPIRES_IN=24h

# 日志配置
LOG_LEVEL=info
LOG_CONSOLE=true

4. 构建项目

npm run build

5. 启动服务

# 开发模式
npm run dev

# 生产模式
npm start

🐳 Docker 部署

使用 Docker Compose

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

手动 Docker 部署

# 构建镜像
docker build -t mcp-kubernetes-server .

# 运行容器
docker run -d \
  --name mcp-kubernetes-server \
  -p 3000:3000 \
  -v ~/.kube/config:/app/.kube/config:ro \
  -e AUTH_ENABLED=true \
  -e JWT_SECRET=your-secret-key \
  mcp-kubernetes-server

☸️ Kubernetes 部署

# 应用部署配置
kubectl apply -f k8s/deployment.yaml

# 检查部署状态
kubectl get pods -l app=mcp-kubernetes-server

# 查看服务
kubectl get svc mcp-kubernetes-server

🔌 多平台集成

支持的客户端平台

平台	状态	集成方式	文档链接
🤖 Dify	✅ 完全支持	HTTP MCP	Dify 集成指南
💬 Claude Desktop	✅ 完全支持	标准 MCP	MCP 客户端集成
🔧 自定义客户端	✅ 完全支持	HTTP/SSE API	API 文档
🌐 Web 应用	✅ 完全支持	REST API	使用示例

快速集成示例

1. Dify 平台集成

在 Dify 中配置 MCP 服务器：

{
  "name": "Kubernetes MCP Server",
  "endpoint": "http://your-server:3000/mcp",
  "auth": {
    "type": "bearer",
    "token": "YOUR_JWT_TOKEN"
  },
  "capabilities": ["tools"]
}

自然语言使用示例：

"显示默认命名空间中的所有 Pod"
"部署一个 nginx 应用，使用 3 个副本"
"获取 nginx Pod 的最近 100 行日志"
"删除名为 test-pod 的 Pod"

2. Claude Desktop 集成

创建 MCP 客户端代理脚本 mcp-client-proxy.js：

const axios = require('axios');

const serverUrl = process.env.MCP_SERVER_URL;
const token = process.env.MCP_AUTH_TOKEN;

process.stdin.on('data', async (data) => {
  try {
    const message = JSON.parse(data.toString());
    const response = await axios.post(serverUrl, message, {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      }
    });
    console.log(JSON.stringify(response.data));
  } catch (error) {
    console.log(JSON.stringify({
      jsonrpc: '2.0',
      id: message?.id || null,
      error: { code: -32603, message: error.message }
    }));
  }
});

然后在 Claude Desktop 配置中：

{
  "mcpServers": {
    "kubernetes": {
      "command": "node",
      "args": ["mcp-client-proxy.js"],
      "env": {
        "MCP_SERVER_URL": "http://your-server:3000/mcp",
        "MCP_AUTH_TOKEN": "YOUR_JWT_TOKEN"
      }
    }
  }
}

3. 自定义客户端集成

class MCPKubernetesClient {
  constructor(serverUrl, token) {
    this.serverUrl = serverUrl;
    this.token = token;
    this.requestId = 1;
  }

  async callTool(name, arguments) {
    const message = {
      jsonrpc: '2.0',
      id: this.requestId++,
      method: 'tools/call',
      params: { name, arguments }
    };

    const response = await fetch(this.serverUrl, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.token}`
      },
      body: JSON.stringify(message)
    });

    return response.json();
  }

  async getPods(namespace = 'default') {
    return this.callTool('kubectl_get', {
      resource: 'pods',
      namespace
    });
  }
}

// 使用示例
const client = new MCPKubernetesClient(
  'http://your-server:3000/mcp',
  'YOUR_JWT_TOKEN'
);

const pods = await client.getPods();
console.log(pods.result);

📡 API 接口

支持的 MCP 方法

方法	描述	参数
`initialize`	初始化连接	协议版本、客户端信息
`tools/list`	获取工具列表	无
`tools/call`	调用工具	工具名称、参数
`resources/list`	获取资源列表	无
`prompts/list`	获取提示列表	无

可用工具

工具名称	功能描述	必需参数	可选参数
`kubectl_get`	获取 K8s 资源	`resource`	`namespace`, `name`
`kubectl_apply`	应用配置	`yaml`	`namespace`
`kubectl_delete`	删除资源	`resource`, `name`	`namespace`
`kubectl_logs`	获取日志	`pod`	`namespace`, `container`, `lines`

API 端点

认证: POST /auth/login
MCP 协议: POST /mcp
SSE 实时: GET /mcp/sse
健康检查: GET /health

📡 API 使用

认证

首先获取访问令牌：

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123"
  }'

MCP 协议调用

使用获取的令牌调用 MCP 接口：

curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

支持的工具

kubectl_get: 获取 Kubernetes 资源
kubectl_apply: 应用资源配置
kubectl_delete: 删除资源
kubectl_logs: 获取 Pod 日志

示例：获取 Pods

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "kubectl_get",
    "arguments": {
      "resource": "pods",
      "namespace": "default"
    }
  }
}

示例：应用部署

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "kubectl_apply",
    "arguments": {
      "yaml": "apiVersion: v1\nkind: Pod\nmetadata:\n  name: test-pod\nspec:\n  containers:\n  - name: nginx\n    image: nginx:latest",
      "namespace": "default"
    }
  }
}

🔧 开发

项目结构

src/
├── auth/              # 认证相关
├── config/            # 配置管理
├── kubernetes/        # Kubernetes API 代理
├── middleware/        # 中间件
├── server/           # MCP 服务器实现
├── utils/            # 工具类
└── index.ts          # 应用入口

开发命令

# 开发模式（热重载）
npm run watch

# 代码检查
npm run lint

# 修复代码格式
npm run lint:fix

# 运行测试
npm test

# 构建项目
npm run build

🔒 安全考虑

更改默认密钥: 生产环境中务必更改 JWT_SECRET
RBAC 权限: 根据需要调整 Kubernetes RBAC 权限
网络安全: 使用 HTTPS 和适当的网络策略
速率限制: 根据需要调整请求频率限制
日志审计: 启用详细的访问日志记录

📊 监控和日志

健康检查

curl http://localhost:3000/health

日志配置

支持多种日志级别和输出格式：

LOG_LEVEL: error, warn, info, debug, verbose
LOG_FORMAT: combined, json, simple
LOG_FILE: 日志文件路径（可选）
LOG_CONSOLE: 控制台输出开关

🤝 贡献

Fork 项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🆘 故障排除

常见问题

Kubernetes 连接失败
- 检查 KUBECONFIG 路径是否正确
- 验证集群访问权限
- 确认网络连接
认证失败
- 检查 JWT 密钥配置
- 验证令牌是否过期
- 确认用户权限
端口冲突
- 修改 PORT 环境变量
- 检查端口是否被占用

调试模式

启用详细日志：

LOG_LEVEL=debug npm run dev

📞 支持

如有问题或建议，请：

查看 Issues 页面
创建新的 Issue
联系维护者

注意: 这是一个开发版本，请在生产环境使用前进行充分测试。

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
docs		docs
examples		examples
k8s		k8s
scripts		scripts
src		src
.env.example		.env.example
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
jest.config.js		jest.config.js
package.json		package.json
tsconfig.json		tsconfig.json

License

huchunlinnk/mcp-remote-server-kubernetes

Folders and files

Latest commit

History

Repository files navigation