mcp_server

使用 MCP 在 RunPod 上执行 Python 代码

此项目支持 AI 助手使用模型上下文协议（MCP）在 RunPod 基础设施上执行 Python 代码。它由两个主要组件组成：

1. 执行 Python 代码的 RunPod Serverless API
2. 连接 RunPod API 并为 AI 助手提供标准化接口的 MCP 服务

系统架构

┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│               │     │               │     │               │
│  AI Assistant │────▶│   MCP Server  │────▶│ RunPod API    │
│  (e.g. Cline) │     │    (Python)   │     │ (Serverless)  │
│               │     │               │     │               │
└───────────────┘     └───────────────┘     └───────────────┘

交互顺序

UML

1. RunPod Serverless 设置

前提条件

• 已安装 Docker
• 拥有 RunPod 账号和 API 密钥
• 具备 Docker 和 Python 基础知识

步骤 1：构建并推送 Docker 镜像

Dockerfile 包含常用的数据科学库和代码处理程序： 当前 Docker 镜像：docker.io/79c2e466/code_handler_serverless

# Clone this repository
git clone https://github.com/yourusername/runpod-python-executor.git
cd runpod-python-executor

# Build the Docker image
docker build -t yourusername/runpod-python-executor:latest .

# Login to Docker Hub
docker login

# Push the image to Docker Hub
docker push yourusername/runpod-python-executor:latest

步骤 2：在 RunPod Serverless 上部署

1. 前往 RunPod.io
2. 导航至 Serverless → Deploy
3. 输入 Docker 镜像 URL：docker.io/79c2e466/code_handler_serverless
4. 配置设置：
   • Worker Type：CPU 或基础 GPU
   • Min/Max Workers：1/3（根据需要调整）
   • Idle Timeout：5 分钟
5. 点击“Deploy”

步骤 3：获取 Endpoint ID

部署完成后，RunPod 会生成一个 Endpoint ID。请复制此 ID，因为配置 MCP 服务时需要用到它。

Serverless API 端点为：https://api.runpod.io/v2/{endpoint_id}/run

你可以使用以下命令测试端点：

curl -X POST \
  https://api.runpod.io/v2/{endpoint_id}/runsync \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_RUNPOD_API_KEY' \
  -d '{
    "input": {
      "code": "print(\"Hello, World!\")"
    }
  }'

2. MCP 服务设置

MCP 服务使用模型上下文协议将 AI 助手连接到你的 RunPod 端点。

前提条件

• 已安装 Python 3.8+
• RunPod API 密钥
• 上述步骤 3 中获取的 RunPod Endpoint ID

步骤 1：安装依赖项

安装 将 MCP 添加到 Python 项目 我们建议使用 uv 管理 Python 项目。在由 uv 管理的 Python 项目中，可通过以下命令将 mcp 添加为依赖项：

uv add "mcp[cli]" 或者，对于使用 pip 管理依赖项的项目：

pip install mcp 运行独立的 MCP 开发工具 使用 uv 运行 mcp 命令：

uv run mcp

pip install mcp requests

步骤 2：配置 MCP 服务

创建名为 runpod_mcp_server.py 的文件，并填入提供的模板代码。更新以下环境变量：

# Update these values
RUNPOD_API_KEY = "your_runpod_api_key"
RUNPOD_ENDPOINT_ID = "your_endpoint_id"  # From serverless deployment

步骤 3：运行 MCP 服务

添加 cline MCP 设置

"PythonServerlessExecutor": {
      "command": "xx/.local/bin/uv",
      "args": [
        "run",
        "xxx/mcp_server/runpod_serverless_mcp_server/server.py"
      ],
      "disabled": false,
      "autoApprove": []
    },

步骤 4：使用 MCP 服务

连接后，你可以使用以下工具：

• execute_python_code：在 RunPod 上运行 Python 代码
• check_runpod_status：检查与 RunPod 的连接状态

使用 Cline 的示例：

Can you run this Python code?
```python
import numpy as np
import matplotlib.pyplot as plt

x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.plot(x, y)
plt.title("Sine Wave")
plt.savefig("sine_wave.png")
print("Generated sine wave plot")

Cline 将使用 MCP 服务执行此代码并返回结果。

示例

工作原理

1. AI 助手（例如 Cline）收到运行 Python 代码的请求
2. 它通过 MCP 协议调用 execute_python_code 工具
3. MCP 服务将代码发送到 RunPod Serverless 端点
4. RunPod 在 Docker 容器中执行代码
5. 执行结果（stdout、stderr、返回代码）会返回给 MCP 服务
6. MCP 服务整理结果并将其发送回 AI 助手
7. AI 助手向用户显示结果

安全注意事项

• 代码在隔离的容器中执行
• 执行时间受到限制，以防止滥用资源
• 在生产环境中使用时，应实施额外的安全措施

故障排除

• MCP 服务连接问题：检查 API 密钥和 Endpoint ID
• 代码执行超时：代码可能过于复杂或陷入无限循环
• 缺少库：检查代码是否需要 Dockerfile 中未包含的库

高级配置

你可以修改以下内容来调整行为：

• MAX_EXECUTION_TIME：更改代码执行超时时间
• Dockerfile：根据需要添加或移除库
• 错误处理：针对特定场景自定义错误消息

为什么选择无服务器而非创建 Pod

出于以下几个重要原因，我们选择使用 RunPod 的无服务器基础设施，而不是创建完整的 Pod：

1. 日志访问限制：RunPod 不提供直接获取已创建 Pod 日志的 API。因此，使用创建 Pod 的方式时，很难捕获代码执行的输出。
2. 连接复杂性：要与 Pod 保持持久连接，需要额外的基础设施来支持 SSH 或其他远程访问方式。
3. 资源管理：即使处于空闲状态，Pod 也会持续运行并产生费用；而无服务器函数只按实际执行时间收费。

无服务器方案的缺点

1. 冷启动延迟：容器启动时，首次执行可能会有延迟（冷启动）。
2. 无持久存储：每次执行都会启动一个全新的环境，因此难以在不同执行之间保持状态。
3. 资源限制：与完整的 Pod 相比，无服务器函数通常可用的 CPU、内存和磁盘资源更有限。 4.有限的 GPU 访问：虽然可以使用 GPU，但无服务器环境中的 GPU 访问限制更多，通常也比使用专用 Pod 更昂贵。