使用说明

🧭 可流式Pod Shell MCP服务器

基于FastMCP的服务器，通过实时流式shell命令执行创建隔离的Kubernetes Pod会话。

📋 概述

此MCP服务器为每个会话自动创建一个专用的Kubernetes Pod，提供：

🔒 孤立的执行环境 每次会话
📡 实时流媒体 stdout/stderr
⏱️ 基于TTL的自动清理 防止吊舱泄漏
🐚 Shell命令执行 内部Pod
📁 文件管理 （创建/删除/列出）
🟢 Node.js代码执行 支持

🏗️ 建筑

┌──────────────┐         ┌──────────────┐         ┌──────────────────┐
│              │         │              │         │   Kubernetes     │
│  MCP Client  │────────▶│  MCP Server  │────────▶│   Cluster        │
│ (Claude/AI)  │         │  (FastMCP)   │         │                  │
└──────────────┘         └──────────────┘         │  ┌────────────┐  │
                                                   │  │ session-   │  │
                                                   │  │ abc123     │  │
                                                   │  └────────────┘  │
                                                   │  ┌────────────┐  │
                                                   │  │ session-   │  │
                                                   │  │ def456     │  │
                                                   │  └────────────┘  │
                                                   └──────────────────┘

🚀 快速开始

先决条件

Python 3.10+
Kubernetes集群（种类、minikube或生产集群）
kubectl 配置
uv （用于Python依赖管理）

安装

克隆存储库
```
git clone <repository-url>
cd pod-mcp
```
使用uv安装依赖项
```
uv pip install -e .
```

设置Kubernetes资源

# Apply RBAC and namespace
kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/serviceaccount.yaml
kubectl apply -f k8s/role.yaml
kubectl apply -f k8s/rolebinding.yaml

在本地运行服务器
```
python run_server.py
```

🛠️ MCP工具

会话管理

`create_session`

创建一个新的隔离Pod会话。

参数：

ttl （int，可选）：生存时间（秒）（默认值：600）
image （str，可选）：容器映像（默认值： busybox:latest)
session_id （str，可选）：自定义会话ID（如果未提供，则自动生成）

例子：

{
  "ttl": 600,
  "image": "node:18-alpine",
  "session_id": "my-session"
}

`delete_session`

删除Pod会话并清理资源。

参数：

session_id （str）：要删除的会话ID

`list_sessions`

列出所有活动会话及其详细信息。

`extend_session`

扩展现有会话的TTL。

参数：

session_id （str）：会话ID
extra_seconds （int）：要添加的额外秒数（默认值：300）

`get_session_status`

获取Pod会话的状态。

参数：

session_id （str）：会话ID

文件操作

`list_files`

列出目录中的文件（流式输出）。

参数：

session_id （str）：会话ID
path （str，可选）：目录路径（默认： /tmp)

`create_file`

创建一个包含内容的文件。

参数：

session_id （str）：会话ID
file_path （str）：新文件的完整路径
content （str）：文件内容

`delete_file`

从Pod中删除文件。

参数：

session_id （str）：会话ID
file_path （str）：文件的完整路径

代码执行

`run_node`

执行Node.js代码（流式输出）。

注：容器映像中需要Node.js（例如。， node:18-alpine)

参数：

session_id （str）：会话ID
code （str）：要执行的JavaScript/Node.js代码

例子：

console.log('Hello from Node.js!');
console.log(process.version);

`run_shell`

执行任意shell命令（流式输出）。

参数：

session_id （str）：会话ID
command （str）：要执行的Shell命令

例子：

"echo 'Hello World' && date && pwd"

🐳 Docker部署

构建图像

docker build -t streamable-pod-mcp:latest .

推送到注册表

docker tag streamable-pod-mcp:latest your-registry/streamable-pod-mcp:latest
docker push your-registry/streamable-pod-mcp:latest

部署到Kubernetes

# Update image in k8s/deployment.yaml
kubectl apply -f k8s/deployment.yaml

⎈Helm安装

安装

helm install pod-mcp ./helm/streamable-pod-mcp \
  --namespace pod-mcp \
  --create-namespace

自定义值

helm install pod-mcp ./helm/streamable-pod-mcp \
  --namespace pod-mcp \
  --set image.repository=your-registry/streamable-pod-mcp \
  --set image.tag=v0.1.0 \
  --set mcpServer.podNamespace=default \
  --set mcpServer.defaultTTL=1200

升级

helm upgrade pod-mcp ./helm/streamable-pod-mcp \
  --namespace pod-mcp

卸载

helm uninstall pod-mcp --namespace pod-mcp

🧪 按种类测试

1.创建种类集群

kind create cluster --name mcp-test

2.加载Docker镜像

# Build image
docker build -t streamable-pod-mcp:latest .

# Load into kind
kind load docker-image streamable-pod-mcp:latest --name mcp-test

3.部署

kubectl apply -f k8s/namespace.yaml
kubectl apply -f k8s/serviceaccount.yaml
kubectl apply -f k8s/role.yaml
kubectl apply -f k8s/rolebinding.yaml
kubectl apply -f k8s/deployment.yaml

4.港口转发

kubectl port-forward -n pod-mcp svc/pod-mcp-server 8000:8000

5.测试

# The server should now be accessible at localhost:8000
curl http://localhost:8000/health

🔐 安全考虑

RBAC权限

服务器需要以下权限：

pods: get, list, watch, create, delete
pods/status: get
pods/exec: create
pods/log: get

资源限制

每个会话Pod都有默认限制：

CPU：200米（限制），100米（请求）
内存：256Mi（限制），128Mi（请求）

命令筛选

⚠️ 警告： 这 run_shell 该工具允许执行任意命令。考虑：

在隔离的命名空间中运行
执行命令白名单
使用网络策略限制Pod网络访问
监控并记录所有命令

📊 监控

查看服务器日志

kubectl logs -n pod-mcp deployment/pod-mcp-server -f

列出会话Pod

kubectl get pods -l managed-by=streamable-pod-mcp

检查TTL监视器

TTL监视器作为后台线程运行，并自动删除过期的Pod。检查服务器日志中是否有以下条目：

TTL watcher started (check interval: 10s)
TTL expired for session abc123, deleting pod...

🎯 使用Claude/Cursor

Claude桌面配置

添加到您的Claude Desktop MCP设置中：

{
  "mcpServers": {
    "pod-shell": {
      "url": "http://localhost:8000",
      "transport": "http"
    }
  }
}

对话示例

User: Create a new session with Node.js

Claude: I'll create a session with Node.js support.
[Calls create_session with image="node:18-alpine"]

Session created: session-abc123

User: Run some JavaScript code to check the Node version

Claude: [Calls run_node with code="console.log(process.version)"]

Output: v18.19.0

User: List files in /tmp

Claude: [Calls list_files with path="/tmp"]

total 0
drwxrwxrwt    2 root     root            40 Nov  2 12:00 .
drwxr-xr-x   17 root     root          4096 Nov  2 12:00 ..

🔧 配置

环境变量

POD_NAMESPACE：会话Pod的Kubernetes命名空间（默认值： default)
IN_CLUSTER：是否在群集中运行（默认值： false)

服务器配置

编辑 run_server.py 自定义：

initialize_server(
    namespace="my-namespace",  # Custom namespace
    in_cluster=False,          # Set True when deployed in-cluster
    start_watcher=True,        # Enable TTL watcher
)

🐛 故障排除

Pod未创建

检查RBAC权限：

kubectl auth can-i create pods --namespace=default --as=system:serviceaccount:pod-mcp:pod-mcp-server

检查服务器日志：

kubectl logs -n pod-mcp deployment/pod-mcp-server

连接被拒绝

验证服务是否正在运行：
```
kubectl get svc -n pod-mcp
```

检查端口转发：

kubectl port-forward -n pod-mcp svc/pod-mcp-server 8000:8000

Pod未删除

检查TTL监视器是否正在运行（检查服务器日志）

手动清理：

kubectl delete pods -l managed-by=streamable-pod-mcp

📚 发展

项目结构

pod-mcp/
├── src/
│   ├── __init__.py
│   ├── pod_manager.py      # Pod lifecycle management
│   ├── executor.py          # Kubernetes exec stream handler
│   └── mcp_server.py        # FastMCP server and tools
├── k8s/                     # Kubernetes manifests
├── helm/                    # Helm chart
├── run_server.py            # Server entry point
├── pyproject.toml           # Python dependencies (uv)
├── Dockerfile               # Container image
└── README.md

运行测试

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests (coming soon)
pytest

代码格式化

black src/

🎯 路线图

[]会话数据的持久卷支持
[]多命名空间管理
[]WebSocket直接流模式
[]通过命令过滤增强安全性
[]指标和Prometheus集成
[]会话快照和恢复
[]支持更多基本映像（Python、Go等）

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

🤝 贡献

欢迎投稿！请打开问题或提交拉取请求。

📧 联系

如有疑问或问题，请打开GitHub issue。

使用说明

🧭 可流式Pod Shell MCP服务器

📋 概述

🏗️ 建筑

🚀 快速开始

先决条件

安装

🛠️ MCP工具

会话管理

create_session

delete_session

list_sessions

extend_session

get_session_status

文件操作

list_files

create_file

delete_file

代码执行

run_node

run_shell

🐳 Docker部署

构建图像

推送到注册表

部署到Kubernetes

⎈Helm安装

安装

自定义值

升级

卸载

🧪 按种类测试

1.创建种类集群

2.加载Docker镜像

3.部署

4.港口转发

5.测试

🔐 安全考虑

RBAC权限

资源限制

命令筛选

📊 监控

查看服务器日志

列出会话Pod

检查TTL监视器

🎯 使用Claude/Cursor

Claude桌面配置

对话示例

🔧 配置

环境变量

服务器配置

🐛 故障排除

Pod未创建

连接被拒绝

Pod未删除

📚 发展

项目结构

运行测试

代码格式化

🎯 路线图

📄 许可证

🤝 贡献

📧 联系

相关 MCP

Kubernetes集群管理MCP服务

Kubernetes MCP服务器

Kubernetes资源管理工具

Kubernetes MCP 服务器

Kubernetes 多集群管理服务

多集群管理MCP服务器

`create_session`

`delete_session`

`list_sessions`

`extend_session`

`get_session_status`

`list_files`

`create_file`

`delete_file`

`run_node`

`run_shell`