runpod-mcp

Runpod MCP

Runpod MCP 服务以结构化工具调用的形式提供 Runpod 控制平面，让支持 MCP 的 Agent 无需调用 Shell 命令即可管理基础设施。它使用的正是 runpodctl 所用的 Runpod REST API。当工具已连接时，优先使用 MCP（参数带类型、错误结构化、无需处理 Shell 引号）。

此技能包含三项功能：连接服务，将每个请求路由到提供相应操作步骤的旅程技能（按意图路由），并负责以下回答规范，所有回复都必须遵循。

对于多步骤任务，请在调用工具前先阅读完整示例。 工具调用很容易发出，也很容易以错误的顺序发出。经过验证的端到端操作序列位于 runpod/golden-paths/README.md（镜像 → 模板 → 端点、Pod → 卷 → 无服务器、多区域、自动扩缩、监控）。旅程技能涵盖单个旅程中的操作步骤；这些路径则说明如何安排整个任务的操作顺序。

连接

如果你也使用 runpodctl/flash，请使用你的 API 密钥作为 Bearer 标头连接托管服务。一个密钥即可验证 MCP 和 CLI（适用于 80% 的情况）：

claude mcp add --transport http runpod -s user https://mcp.getrunpod.io/ \
  --header "Authorization: Bearer $RUNPOD_API_KEY"

普通 OAuth（“使用 Runpod 登录”；用户可通过交互式 npx @runpod/mcp-server@latest add 进行设置）仅适用于 MCP：CLI 仍未通过验证，因此仅在只使用 MCP 的任务中使用。本地 stdio 会使用你的密钥将服务作为子进程运行。这些方式及密钥与 OAuth 之间的权衡，详见 reference/connect.md。连接后，重新连接客户端（在 Claude Code 中使用 /mcp），以加载工具。

验证服务是否已运行（使用 MCP 前务必执行）： 在 Claude Code 中运行 /mcp。 runpod 应显示为已连接，而不是需要身份验证（如果显示后者，请先在该处登录；捆绑的插件服务会注册 URL，但在完成身份验证前不会运行）。通过请求 list-endpoints，确认实际调用成功。 如果完全没有 runpod 工具，说明服务尚未连接：重新运行上方的安装命令，或改用 runpodctl 完成此任务。

检查服务版本（以及它所调用的 REST API）： MCP initialize 握手会在 serverInfo.version 中返回版本。在 Claude Code 中运行 /mcp 可查看该版本，也可以直接探测托管服务：

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
| curl -s -X POST https://mcp.getrunpod.io/ \
    -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" \
    -H "Authorization: Bearer $RUNPOD_API_KEY" -d @-

服务是事实依据

连接后，请查阅服务。不要凭记忆推断它的工具。

1. 工具列表和所有参数均来自客户端对已连接服务的实际视图：Claude Code 中的 /mcp 或 tools/list。每个工具都包含自己的参数说明，这些说明根据 Runpod 的 REST v2 契约生成。在确认某项能力存在或不存在之前，请先查阅该列表。当旅程技能中的工具绑定与实时工具列表不一致时，以实时列表为准。
2. 服务提供的这些技能与本插件版本相同：read-guide（从 read-guide runpod-mcp 开始）以及 runpod://guides/<id> 资源。安装此插件后，下方的旅程技能就是操作步骤；对于未安装插件的 Agent，服务提供的指南内容相同。
3. 线协议契约是 Runpod v2 OpenAPI 文档；对于工具界面未涵盖的字段，请参阅 https://api.runpod.io/v2/openapi.json。

有关概念（Pod 与无服务器、GPU 选择、存储），请阅读 ../runpod-usage/。

使用 MCP 还是 runpodctl

• 以下情况使用此路径：基础设施的增删改查、浏览或部署现有的 Hub 条目，或调用已连接服务公开的无服务器任务。请根据路由器能力矩阵选择路径。大量任务或日志输出请写入文件。
• 以下情况改用 runpodctl：文件传输（send/receive）、SSH 密钥管理、doctor 设置、模型缓存、任何仅限 Shell 的 Agent，或用户需要可复现的命令时。
• 每次创建 GPU 时都要指定 CUDA 最低版本。 create-pod 和 create-endpoint 接受 gpu.minCudaVersion（默认值为 "12.8"；只有 CUDA-13 镜像才使用 "13.0"）；create-template 接受 allowedCudaVersions。如果不指定最低版本，创建操作会接受任何主机 CUDA 版本，较新的镜像可能会部署到 CUDA 版本过低、无法运行它的主机上。了解选择 12.8 的原因以及何时使用 13.0： runpod-usage gpu-selection。
• 以下情况将 Pod 创建交给 runpodctl：需要多 GPU 优先级列表时（v2 create-pod 只接受一种 GPU 类型；请先检查实时 schema，不要想当然，并留意成功创建时是否带有 _warning）；或者需要同时指定模板 + CPU 时，因为 v2 无法表达这种组合。在 MCP 中单独指定任一项都没问题：templateId（传入的每个字段都会替换模板中的整个对应值，而非与其合并）或 computeType: "CPU"。
• **不适用此路径：**编写模板项目或 Hub 条目文件（→ runpod-build-template）；使用 Flash 编写或部署自己的 Python（→ flash）；下载模型或构建并推送镜像（→ companion-clis）。

根据意图选择路径

用户想要……	流程技能
了解有哪些 GPU、worker、endpoint，哪些适合某个模型以及费用	discovery
创建/检查/更新/删除 Pod、endpoint、模板、卷、账户密钥、SSH 密钥、集群；盘点账户资源	lifecycle-crud
为某个模型/工作负载启动无服务器 endpoint，并通过实际任务验证	serverless-deploy
将 ComfyUI 工作流（workflow.json、自定义 Civitai 模型/LoRA）托管为 endpoint	serverless-deploy，然后参阅其 ComfyUI 参考文档
租用/配置交互式 GPU Pod；创建 Pod 后暂停/停止，以便之后使用	pod-deploy
诊断故障或异常 Pod（GPU 数量为 0、CUDA、崩溃、502）	pod-doctor
运维现有 endpoint：任务、扩缩容、worker、日志	endpoint-ops
了解或降低开支；查看账单明细	cost-audit
工具可能不支持的操作（文件传输、在 Pod 中执行命令）	下方的能力边界

能力边界——如实说明，绝不伪装

此接口通过 Runpod MCP 工具管理基础设施。它不支持：SSH 会话、与 Pod 之间的文件传输、本地镜像构建、向卷下载模型或交互式终端。任务需要这些功能时，请说明这些工具不支持，并指出对应路径：文件传输（send/receive）、SSH 设置和模型上传使用 runpodctl；在 Pod 中执行命令使用 SSH 或控制台 Web 终端；以代码为先的 Serverless 部署使用 Flash SDK；Pod 迁移使用控制台。绝不要虚构功能，也不要悄悄省略任务的这部分内容。

在认定某项功能缺失前，请先检查当前提供的工具列表：账户密钥和 Instant Clusters 曾经只能通过控制台使用，现在已作为工具提供。关于各项缺失功能的替代方案，以及如何规范地回答此类问题，请参阅 reference/api-boundary.md。

修改前先读取实时状态

即使指南或之前的会话中提到过模板 ID、GPU 库存或价格、资源状态，也必须先通过 list 或 get 工具确认，再执行操作。

回复约定

每条 Runpod 回复都遵循以下规则。Journey 技能会添加特定于 Journey 的规则和报告模板，但绝不会削弱这些规则。

事实来自工具读取，并作为事实陈述。

• 在答案中注明每项事实背后的读取结果（例如“来自读取的模板”“来自 list-hub-repos”“来自 Pod 日志”）：未经读取就陈述镜像、价格或库存数据，不能作为证据，无论这些数据是否正确。
• 引用刚刚读取到的真实数值、名称和 ID，不要凭记忆，也不要用模糊的近似值。ID 必须原样引用。
• 明确陈述当前库存／状态（“EU-RO-1 的 RTX 4090：当前有货”），绝不要说“应该有”“可能有”或“稍后再查”。刚刚进行的读取就是核查。
• 绝不自相矛盾：如果表格显示某张显卡有货，摘要就不能说它已售罄。

明确承诺；不要含糊，也不要推迟。

• 诊断应从证据中选出一个最可能的原因和具体修复方案，而不是列出一堆可能性，或说“运行这些命令再告诉我”。
• 如果账户状态使问题不成立（没有部署任何内容、支出为零），就用一句话如实说明，然后停止。坦诚地留空也是完整回答。
• 绝不要向用户索要工具本可获取的信息。继续使用现有工具；只有用户才知道的信息才询问用户，例如他们的凭据、是否有意执行破坏性操作、产品选择。
• create-cluster 必须始终等待用户明确同意：在用户于当前对话中看到节点数、每个节点的 GPU 数量、数据中心和从目录读取结果得出的每小时总价，并明确表示同意之前，绝不要调用它。用户要求创建集群时，先提供该方案和价格；创建操作须等待用户同意。
• 当请求指定了类别但未指定具体项目（如“小模型”“24 GB 显卡”、只给出镜像名称却未说明设置），请选择文档规定的默认选项，用一行说明所选内容，然后继续。用户未提及某项设置，绝不是停止的理由；只有错误的猜测可能导致高额支出或数据丢失时才停止。
• 用户要求部署、配置或创建某项内容，即表示同意执行该创建操作。在同一条回复中引用目录读取结果中的每小时价格并执行操作；绝不要以“要我继续吗？”结束本轮对话。有两种情况须等待明确同意：集群（见上文），以及用户未明确要求的持续收费项目，例如常驻 Worker。对于这类项目，先创建闲置时不产生费用的部分，再说明每小时和每月的持续费用并询问用户是否要启用。 变更仅适用于本次对话创建的资源，或用户指定的资源。
• 你可以停止、更新或删除本次对话中由你自己的工具调用创建的资源。你也可以按 ID 或明确无歧义的名称，更改请求中用户指定的那个资源（例如某个端点上的设置、某个队列中的一个作业），但只能执行用户要求的更改：只有用户要求删除时，才能删除用户指定的资源。用户的指令就是该资源的授权，因此应直接执行更改，而不是把控制台操作步骤交给用户。除此之外，资源归属只能依据你创建资源时的输出，绝不能依据你通过列表找到的名称。看起来像临时资源的名称、自动生成的 slug，或熟悉的前缀，都不能作为归属依据。
• 清理或削减成本的指令不会扩大这项授权，无论措辞多么急切。对于无法归属于本次对话的资源，完整答复应是一份审计报告：列出你检查了什么、哪些资源符合条件、它们的 ID，以及用户应采取的确切操作。这就是完整答复，不是推脱。果断执行的规则绝不授权你修改不属于你的资源。
• 当本次对话创建的资源已无任何剩余时，应原样说明这一点，并且不要触碰任何资源。
• 每次写入后都要进行一次全新的读取。创建或更新后，重新读取资源并确认你设置的字段；删除后，重新读取并确认资源已不存在；取消作业或清空队列后，重新读取作业或队列。更改设置时，还要在写入前读取当前值，以便答复能列出读取到的更改前和更改后数值。写入调用自身返回的响应不算读取结果，最终答复必须引用读取结果显示的内容。
• 对于你未创建的资源，权限错误就是正确答案，而不是需要克服的障碍：将其报告为超出范围。绝不要重试，也不要建议用户改用限制更少的会话或密钥来绕过限制。

最终答复必须独立完整。

• 结尾应提供用户无需向上翻阅即可采取行动的摘要：任务产生的 ID、URL、价格和命令都应列在其中。不要说“上面的链接”，也不要指向之前的对话轮次。

尽可能推进工作。

• 优先使用服务端等待（wait 参数），而不是让用户自行循环轮询；每次等待之间都要检查状态。如果等待时间超出工具支持的时长，应报告有证据支持的状态（已创建的内容、已提交的内容、工作器状态），并给出建议的下一步。可以表示愿意继续监控，但不能在等待过程中悄然停止。

如实说明失败，胜过编造成功。

• 根据观察到的证据（错误正文、工作器状态、日志行）报告失败。没有证明结果的产物，绝不能宣称成功。
• 缺少凭据或能力时，应如实说明，并告知你如何确认这一点，以及用户必须提供什么。

仅使用提供给你的工具。

• 如果本次会话中没有某个工具，就使用已有工具继续工作；已经读取的信息可以直接分析。绝不要因为需要新工具访问权限而停滞任务。

报告习惯（资源清单、成本、部署报告）：

• 枚举内容最好用表格呈现，并列出每项资源的名称和 ID。
• 所有美元金额都必须来自本轮对话中读取的计费或定价信息；应同时列出总额和各项金额，并显示空类别，不能默默省略。
• 开篇直接给出用户要求的数字或结论。

源码与文档

• 服务端源码：https://github.com/runpod/runpod-mcp
• 软件包（npm）：https://www.npmjs.com/package/@runpod/mcp-server
• 托管端点：https://mcp.getrunpod.io/
• 文档：https://docs.runpod.io