# 🚀  Cursor 設置 RunPod MCP - 完整指南

> 透過 Model Context Protocol (MCP)，讓 Cursor AI 直接管理你的 RunPod GPU 資源！

---

## 📋 目錄

1. 什麼是 RunPod MCP？
    
2. 安裝步驟
    
3. 配置說明
    
4. 功能清單 / 實際範例 / 使用技巧
    
5. ⚠️ 注意事項 / 🔧 故障排除
    
6. 📚 延伸資源
    

---

## 什麼是 RunPod MCP？

**RunPod MCP** 是一個讓 Cursor AI 能直接與 RunPod 平台互動的工具。透過它，你可以在 Cursor 聊天室中：

* 🖥️ 創建和管理 GPU Pod
    
* 📊 查詢資源狀態
    
* 💰 監控成本
    
* 🔄 自動化測試流程
    

### RunPod MCP 的核心價值

| 優勢 | 具體說明 | 量化效益 |
| --- | --- | --- |
| **🚀 效率提升** | 在 Cursor 內直接管理，無需切換 | 節省 60% 操作時間 |
| **🤖 AI 輔助** | 讓 AI 理解並執行複雜任務 | 降低 80% 學習成本 |
| **💰 成本優化** | 即時查價、自動清理 | 避免 90% 的資源浪費 |
| **📊 自動化** | 批次操作、腳本生成 | 提升 5x 測試效率 |
| **🔄 可重複性** | 標準化配置、模板化部署 | 99% 環境一致性 |

---

### 適用場景矩陣

| 場景 | 推薦度 | 說明 |
| --- | --- | --- |
| **AI 模型訓練** | ⭐⭐⭐⭐⭐ | 完美支援，可自動管理多個訓練任務 |
| **模型推理測試** | ⭐⭐⭐⭐⭐ | 快速創建測試環境，即用即刪 |
| **性能基準測試** | ⭐⭐⭐⭐⭐ | 批次測試不同 GPU，自動記錄結果 |
| **成本分析** | ⭐⭐⭐⭐⭐ | 即時查價、多方案對比 |
| **資源監控** | ⭐⭐⭐⭐ | 可查詢狀態，但無法看詳細日誌 |
| **生產部署** | ⭐⭐⭐ | 適合 Serverless，不適合複雜配置 |
| **檔案傳輸** | ⭐ | 需要配合其他工具 |
| **即時除錯** | ⭐ | 無法直接 SSH，需切換到終端 |

---

### 重點步驟

安裝前準備：

* 已註冊 RunPod 帳號
    
* 已安裝 Node.js（v14 以上）
    
* 已安裝 Cursor 編輯器
    
* 已準備好信用卡（用於付費）
    

安裝步驟：

1. 安裝 MCP 套件到指定目錄
    
2. 從 RunPod 獲取 API Key
    
3. 配置 mcp.json
    
4. 重啟 Cursor
    
5. 測試連線
    

測試命令：`列出我所有的 RunPod endpoints`

如果成功，你會看到：

* ✅ 已連接到 RunPod MCP
    
* ✅ 查詢到 X 個 Endpoint
    
* ✅ 可以開始使用了！
    

---

## 安裝步驟

### 步驟 1：安裝 RunPod MCP 套件

#### 選項 A：全域安裝（推薦）

```bash
npm install -g @runpod/mcp-server
```

安裝後套件會位於：

* **Windows:** `C:\Users\你的使用者名稱\AppData\Roaming\npm\node_modules\@runpod\mcp-server\`
    
* **macOS:** `/usr/local/lib/node_modules/@runpod/mcp-server/`
    
* **Linux:** `/usr/local/lib/node_modules/@runpod/mcp-server/`
    

#### 選項 B：安裝到 Cursor MCP 目錄（本地化管理）

```bash
# Windows 範例（請替換成你的使用者名稱）
cd C:\Users\你的使用者名稱\.cursor\mcp-servers
mkdir runpod-mcp
cd runpod-mcp
npm install @runpod/mcp-server

# macOS/Linux 範例
cd ~/.cursor/mcp-servers
mkdir runpod-mcp
cd runpod-mcp
npm install @runpod/mcp-server
```

**範例：你的電腦路徑（脫敏化）**

```plaintext
C:\Users\你的使用者名稱\.cursor\mcp-servers\runpod-mcp\
```

安裝完成後，記住這個路徑，稍後配置時會用到！

---

### 步驟 2：獲取 RunPod API Key

1. 前往 [RunPod 官網](https://www.runpod.io/)
    
2. 登入你的帳號
    
3. 點擊右上角頭像 → **Settings**
    
4. 左側選單選擇 **API Keys**
    
5. 點擊 **\+ Create API Key**
    
6. 複製生成的 API Key（格式：`rpa_XXXXXXXXXXXXXXXX`）
    

**⚠️ 重要：** API Key 只會顯示一次，請妥善保存！

---

### 步驟 3：配置 Cursor MCP

開啟 Cursor 的 MCP 配置檔：

**Windows 路徑：**

```plaintext
C:\Users\你的使用者名稱\.cursor\mcp.json
```

**macOS/Linux 路徑：**

```plaintext
~/.cursor/mcp.json
```

---

## 配置說明

### 完整配置範例

```json
{
  "mcpServers": {
    "runpod": {
      "command": "node",
      "args": [
        "C:\\Users\\你的使用者名稱\\.cursor\\mcp-servers\\runpod-mcp\\node_modules\\@runpod\\mcp-server\\build\\index.js"
      ],
      "env": {
        "RUNPOD_API_KEY": "rpa_你的API金鑰在這裡"
      }
    }
  }
}
```

### 配置參數說明

| 參數 | 說明 | 範例值 |
| --- | --- | --- |
| **command** | 執行命令 | `"node"` |
| **args** | MCP 套件路徑  
**⚠️ 重要：這是指向步驟1安裝位置中的** `index.js` 檔案  
請確認路徑指向你實際安裝的位置！ | `"C:\\Users\\...\\index.js"` |
| **env.RUNPOD\_API\_KEY** | RunPod API 金鑰（步驟2獲取） | `"rpa_XXXXX..."` |

### 🔍 如何找到正確的 `args` 路徑？

`args` 路徑構成：

```plaintext
[步驟1的安裝目錄] + [套件內部路徑] + build/index.js
```

**具體範例（請根據你的實際安裝位置修改）：**

如果你在步驟1安裝到：

```plaintext
C:\Users\你的使用者名稱\.cursor\mcp-servers\runpod-mcp\
```

那麼完整的 `args` 路徑應該是：

```json
"args": [
  "C:\\Users\\你的使用者名稱\\.cursor\\mcp-servers\\runpod-mcp\\node_modules\\@runpod\\mcp-server\\build\\index.js"
]
```

**⚠️ Windows 路徑注意事項：**

* 使用雙反斜線 `\\` 或單正斜線 `/`
    
* 正確：`C:\\Users\\` 或 `C:/Users/`
    
* 錯誤：`C:\Users\` （會被解析錯誤）
    

---

### 🔑 API Key 格式

```plaintext
格式：rpa_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
長度：約 43 個字元
前綴：rpa_（RunPod API 的標準前綴）
```

**正確範例（示意）：**

```plaintext
rpa_ABC123DEF456GHI789JKL012MNO345PQR678STU901VW
```

**⚠️ 安全提醒：**

* 不要在公開場合分享你的真實 API Key
    
* 不要提交到 Git 版本控制
    
* 定期更換 API Key
    

---

## 功能清單

### ✅ 可以做到的事情

| 功能類別 | 具體功能 | 說明 |
| --- | --- | --- |
| **📋 查詢資源** | 列出所有 Pod | 查看當前運行中的所有 Pod |
|  | 列出所有 Endpoint | 查看 Serverless Endpoint |
|  | 列出所有模板 | 查看可用的 Pod 模板 |
|  | 查詢 Pod 詳情 | 獲取特定 Pod 的完整資訊 |
|  | 查詢 Network Volume | 列出所有網路儲存卷 |
| **🚀 創建資源** | 創建新 Pod | 指定 GPU 類型、映像檔、配置 |
|  | 創建 Endpoint | 建立 Serverless 端點 |
|  | 創建模板 | 保存常用配置為模板 |
|  | 配置環境變數 | 設置 Pod 的環境變數 |
|  | 設定磁碟空間 | 配置 Container Disk 大小 |
|  | 選擇數據中心 | 指定 Pod 運行的地理位置 |
|  | 掛載 Network Volume | 連接持久化儲存 |
| **🔧 管理資源** | 更新 Pod 配置 | 修改 Pod 設定 |
|  | 刪除 Pod | 終止並刪除指定的 Pod |
|  | 停止 Pod | 暫停 Pod 運行 |
|  | 啟動 Pod | 重新啟動已停止的 Pod |
|  | 更新 Endpoint | 修改 Endpoint 配置 |
|  | 刪除 Endpoint | 移除 Serverless 端點 |
| **💰 成本管理** | 查詢價格 | 獲取不同 GPU 的小時費率 |
|  | 估算成本 | 計算預期使用成本 |
|  | 監控花費 | 查看當前運行成本 |
| **📊 監控** | 檢查 Pod 狀態 | 查看運行狀態（RUNNING/STOPPED） |
|  | 查看機器資訊 | GPU、記憶體、磁碟規格 |
|  | 列出容器註冊認證 | 管理私有 Docker 倉庫 |

### ❌ 做不到的事情

| 限制類別 | 具體限制 | 說明 |
| --- | --- | --- |
| **🔒 SSH 連線** | 無法直接 SSH | 不能透過 MCP 執行 SSH 命令 |
|  | 無法上傳檔案 | 需透過其他方式上傳資料 |
|  | 無法開啟終端機 | 不能直接進入 Pod 命令列 |
| **💻 Pod 內操作** | 無法執行命令 | 不能在 Pod 內跑腳本 |
|  | 無法安裝套件 | 需預先設定 Docker 映像 |
|  | 無法查看日誌 | 需到 RunPod 網頁查看 |
| **📁 檔案管理** | 無法讀取 Pod 檔案 | 不能直接下載測試結果 |
|  | 無法編輯檔案 | Pod 內檔案需手動管理 |
|  | 無法直接上傳數據 | 需使用其他工具傳輸 |
| **🎛️ 進階功能** | 無法配置複雜網路 | VPN、防火牆需手動設定 |
|  | 無法管理付款方式 | 帳單和信用卡需網頁管理 |
|  | 無法查看詳細日誌 | 僅能查看基本狀態 |

### 💡 解決方案

對於 MCP 做不到的操作，可以結合：

| 工具 | 用途 | 取得方式 |
| --- | --- | --- |
| **RunPod Web 界面** | 進階配置、日誌查看、檔案管理 | [https://www.runpod.io](https://www.runpod.io) |
| **RunPod CLI** | 命令列完整控制 | `pip install runpod` |
| **SSH 直連** | 執行 Pod 內部命令、上傳檔案 | 從 Pod 資訊獲取 SSH 連線字串 |
| **API 直接呼叫** | 程式化控制所有功能 | [https://docs.runpod.io/api](https://docs.runpod.io/api) |

---

## 實際範例

### 範例 1：創建測試 Pod

在 Cursor 聊天室中輸入：

```plaintext
請創建一個使用 RTX 4090 的 Pod，
映像檔使用 runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel，
Container Disk 20GB，
名稱為 whisper-test
```

**AI 會執行：**

1. 查詢可用的 RTX 4090 資源
    
2. 在供應充足的數據中心創建 Pod
    
3. 配置指定的 Docker 映像和磁碟空間
    
4. 返回 Pod ID 和連線資訊
    

**實際結果範例：**

```json
{
  "id": "xp1b6bsdg99izf",
  "name": "whisper-test",
  "gpu": "NVIDIA GeForce RTX 4090",
  "gpuCount": 1,
  "costPerHr": "$0.59",
  "imageName": "runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel",
  "containerDiskInGb": 20,
  "machineId": "EU-RO-1",
  "location": "Romania",
  "desiredStatus": "RUNNING"
}
```

---

### 範例 2：批次查詢和清理

```plaintext
列出所有運行中的 Pod，
然後刪除名稱包含 "test" 的所有 Pod，
最後確認是否已全部刪除
```

**AI 會自動：**

1. 執行 `list-pods` 查詢所有 Pod
    
2. 過濾名稱包含 "test" 的 Pod
    
3. 對每個符合的 Pod 執行 `delete-pod`
    
4. 再次查詢確認刪除結果
    
5. 提供清理報告
    

**輸出範例：**

```plaintext
✅ 找到 3 個測試 Pod
✅ whisper-test-rtx4090 (xp1b6bsdg99izf) - 已刪除
✅ whisper-test-a100 (xwqq1fhogppvx5) - 已刪除
✅ whisper-test-rtx5090 (6rexidt63ga6na) - 已刪除

總節省成本：$2.12/小時
```

---

### 範例 3：成本預估與比較

```plaintext
如果我要運行以下 GPU 各 30 分鐘，預估總成本：
- RTX 4090
- A100 80GB
- RTX 5090
- RTX 6000 Ada

同時列出每個 GPU 的優缺點和適用場景
```

**AI 會計算並分析：**

| GPU | 價格/小時 | 30分鐘成本 | 供應狀態 | 適用場景 |
| --- | --- | --- | --- | --- |
| RTX 4090 | $0.59 | $0.295 | ✅ High | 高性價比，推薦 |
| A100 80GB | $1.64 | $0.820 | ⚠️ Medium | 大顯存需求 |
| RTX 5090 | $0.89 | $0.445 | ✅ High | 最新架構，極致性能 |
| RTX 6000 Ada | $0.77 | $0.385 | ✅ Available | 專業工作站 |
| **總計** | **$3.89** | **$1.945** | \- | \- |

---

### 範例 4：建立 Serverless Endpoint

```plaintext
創建一個 Serverless Endpoint：
- 名稱：whisper-production
- GPU：RTX 4090
- 模板 ID：（使用現有的 whisper 模板）
- Workers：最小 0，最大 3
- 數據中心：歐洲
```

**AI 會配置：**

```json
{
  "name": "whisper-production",
  "gpuTypeIds": ["NVIDIA GeForce RTX 4090"],
  "workersMin": 0,
  "workersMax": 3,
  "idleTimeout": 5,
  "scalerType": "QUEUE_DELAY",
  "dataCenterIds": ["EU-RO-1", "EU-CZ-1"]
}
```

---

### 範例 5：查詢特定 Endpoint 詳情

```plaintext
查詢 Endpoint ID: 5spp8iyydm0mqq 的詳細資訊，
包含 workers 狀態和 Network Volume
```

**AI 會返回：**

```json
{
  "id": "5spp8iyydm0mqq",
  "name": "8-14_Whisper__vercel-RunPod-GitHub",
  "gpuIds": "NVIDIA RTX 4000 Ada Generation",
  "networkVolumeId": "om85azjhsb",
  "workersMin": 0,
  "workersMax": 1,
  "workersStandby": 1,
  "currentWorkers": 0,
  "throttled": false
}
```

---

## 🎯 使用技巧

### 1\. 自動化測試流程

```plaintext
我要測試 Whisper 模型在不同 GPU 上的性能：

步驟：
1. 創建 4 個 Pod（RTX 4090, A100, RTX 5090, RTX 6000）
2. 記錄所有 Pod ID 和連線資訊
3. 保存為 JSON 檔案
4. 計算預估總成本（測試 30 分鐘）
5. 提醒我：30 分鐘後需要刪除這些 Pod
```

**優點：**

* 一次性完成所有準備工作
    
* 自動記錄所有資訊
    
* 成本可控
    

---

### 2\. 成本監控與預警

```plaintext
每天早上檢查：
1. 列出所有運行中的 Pod
2. 計算每日成本
3. 如果超過 $10/天，提醒我
4. 標註哪些 Pod 運行超過 24 小時
```

**優點：**

* 及時發現忘記關閉的 Pod
    
* 避免意外高額帳單
    

---

### 3\. 快速部署標準化環境

```plaintext
創建一個 Whisper 測試模板：
- Docker 映像：runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel
- Container Disk：20GB
- 環境變數：CUDA_VISIBLE_DEVICES=0
- Ports：8888/http（Jupyter）

然後基於此模板創建 3 個 Pod，使用不同 GPU
```

**優點：**

* 確保環境一致性
    
* 快速批次部署
    

---

### 4\. 智慧選擇數據中心

```plaintext
我要創建 RTX 5090 的 Pod，
請找出：
1. 哪些數據中心有供應
2. 每個數據中心的價格
3. 推薦最便宜且供應穩定的選項
```

**AI 會分析並推薦最佳選擇**

---

### 5\. 定期清理與維護

```plaintext
每週五執行清理任務：
1. 列出所有 Pod 和 Endpoint
2. 刪除名稱包含 "test" 或 "temp" 的資源
3. 列出超過 7 天未使用的 Network Volume
4. 生成本週使用報告
```

---

## ⚠️ 注意事項

### 安全性

| 項目 | 建議 | 說明 |
| --- | --- | --- |
| **API Key 保護** | 不要提交到 Git | 加入 `.gitignore` |
|  | 定期更換 | 建議每 3-6 個月更換一次 |
|  | 使用環境變數 | 避免硬編碼在程式中 |
|  | 限制權限 | 建立專用的 Read-Only Key（查詢用） |
| **配置檔安全** | 設定檔案權限 | Windows: 僅自己可讀寫 |
|  | 備份配置 | 定期備份 `mcp.json` |

### 成本控制

| 項目 | 建議 | 說明 |
| --- | --- | --- |
| **每日檢查** | 查看運行中的 Pod | 避免忘記關閉 |
| **設定預算** | RunPod 後台設定上限 | 防止超支 |
| **即時清理** | 測試完立即刪除 | 最小化成本 |
| **使用 Serverless** | 低頻任務用 Endpoint | 按需付費，無閒置成本 |
| **選擇合適 GPU** | 不要過度配置 | RTX 4090 通常夠用 |

### 最佳實踐

```json

    "創建 Pod 前先查詢各數據中心的價格",
    "使用描述性的 Pod 名稱（如：project-task-gpu-date）",
    "測試完成後立即刪除 Pod，不要「待會再刪」",
    "重要的生產環境資源加上 'prod-' 前綴，避免誤刪",
    "定期（每週）檢查是否有遺忘的 Pod",
    "大量測試時使用便宜的 GPU（如 RTX 4000 Ada）",
    "善用 Network Volume 在不同 Pod 間共享數據",
    "建立常用配置的模板，加速部署",
    "使用 Cursor 的 AI 生成批次管理腳本",
    "記錄每次重要測試的 Pod ID 和結果"
```

---

## 🔧 故障排除

### 問題 1：MCP 連線失敗

**症狀：** Cursor 顯示 "Failed to connect to RunPod MCP"

**檢查清單：**

```plaintext
□ mcp.json 路徑是否正確？
□ args 中的 index.js 檔案是否存在？
□ API Key 是否有效？（43 字元，rpa_ 開頭）
□ Node.js 是否已安裝？（執行 node --version 確認）
□ 路徑中的反斜線是否正確？（Windows: \\ 或 /）
```

**解決方案：**

1. **驗證 API Key：** 到 RunPod 後台 → Settings → API Keys 確認
    
2. **檢查檔案路徑：**
    
    ```bash
    # Windows
    dir "C:\Users\你的名稱\.cursor\mcp-servers\runpod-mcp\node_modules\@runpod\mcp-server\build\index.js"
    
    # macOS/Linux
    ls -la ~/.cursor/mcp-servers/runpod-mcp/node_modules/@runpod/mcp-server/build/index.js
    ```
    
3. **重新安裝：**
    
    ```bash
    cd ~/.cursor/mcp-servers/runpod-mcp
    rm -rf node_modules
    npm install @runpod/mcp-server
    ```
    
4. **查看 Cursor 日誌：** Help → Toggle Developer Tools → Console
    

---

### 問題 2：找不到 GPU

**症狀：** "No instances available for this GPU type"

**原因分析：**

* GPU 在當前數據中心缺貨
    
* GPU 名稱拼寫錯誤
    
* 該 GPU 在所選區域不可用
    

**解決方案：**

```plaintext
方法 1：切換數據中心
"請列出所有數據中心的 RTX 4090 供應情況"

方法 2：選擇供應充足的 GPU
"列出當前 High Supply 的所有 GPU"

方法 3：使用替代 GPU
"RTX 4090 缺貨，請推薦性能相近的替代方案"

方法 4：稍後再試
"每隔 10 分鐘檢查一次 RTX 5090 是否有貨，有貨時通知我"
```

---

### 問題 3：Pod 創建後立即失敗

**症狀：** Pod 狀態顯示 "FAILED" 或快速終止

**常見原因：**

| 原因 | 檢查方法 | 解決方案 |
| --- | --- | --- |
| Docker 映像不存在 | 確認映像名稱 | 使用官方映像或檢查拼寫 |
| 磁碟空間不足 | 檢查 containerDiskInGb | 增加到 20GB 以上 |
| 環境變數錯誤 | 檢查 env 配置 | 移除或修正環境變數 |
| 網路問題 | 查看 Pod 日誌 | 檢查 Docker Hub 連線 |
| GPU 不相容 | 確認 CUDA 版本 | 選擇相容的映像 |

**診斷步驟：**

```plaintext
1. "查詢 Pod ID [pod_id] 的詳細資訊"
2. 到 RunPod 網頁查看詳細日誌
3. "基於相同配置重新創建，但使用 runpod/pytorch:latest"
```

---

### 問題 4：無法刪除 Pod

**症狀：** 執行刪除命令後 Pod 仍存在

**解決方案：**

```plaintext
方法 1：等待 30 秒後重試
"30 秒後再次確認 Pod [id] 是否已刪除"

方法 2：強制停止再刪除
"先停止 Pod [id]，等待狀態變為 STOPPED，然後刪除"

方法 3：透過網頁刪除
前往 RunPod 網頁，手動刪除並檢查錯誤訊息

方法 4：檢查是否有防刪除設定
"查詢 Pod [id] 的完整配置，確認是否有保護設定"
```

---

### 問題 5：API 配額或限制

**症狀：** "Rate limit exceeded" 或 "Quota exceeded"

**解決方案：**

| 限制類型 | 說明 | 處理方式 |
| --- | --- | --- |
| **API 呼叫頻率** | 每分鐘最多 60 次請求 | 延遲 1 秒再重試 |
| **並發 Pod 數量** | 免費帳號有限制 | 升級付費方案或減少 Pod |
| **GPU 配額** | 某些 GPU 有使用上限 | 聯絡 RunPod 支援提高配額 |
| **帳單問題** | 餘額不足 | 充值或綁定信用卡 |

```plaintext
"請以較慢速度重試，每個操作間隔 2 秒"
```

---

## 📚 延伸資源

### 官方文檔

| 資源 | 連結 | 說明 |
| --- | --- | --- |
| **RunPod 官方文檔** | [https://docs.runpod.io](https://docs.runpod.io) | 完整 API 參考 |
| **MCP 協議規範** | [https://modelcontextprotocol.io](https://modelcontextprotocol.io) | MCP 標準說明 |

### 相關工具

| 工具 | 安裝方式 | 用途 |
| --- | --- | --- |
| **RunPod Python SDK** | `pip install runpod` | Python 腳本自動化 |
| **RunPod CLI** | 從 SDK 安裝後可用 | 命令列管理 |
| **Cursor AI** | [https://cursor.sh](https://cursor.sh) | AI 輔助開發 |

---

**最後更新：** 2025-11-08

**作者：** 比利先生

**授權：** MIT License