runpod-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Runpod MCP

The Runpod MCP server exposes Runpod's control plane as structured tool calls, so an MCP-capable agent can manage infrastructure without shelling out. It is the same Runpod REST API that

runpodctl

uses — pick MCP when its tools are connected (typed params, structured errors, no shell quoting).

Runpod MCP服务器将Runpod的控制平面以结构化工具调用的形式暴露出来，因此支持MCP的Agent无需调用外部shell即可管理基础设施。它使用与

runpodctl

相同的Runpod REST API——当MCP工具已连接时选择使用它（具备类型化参数、结构化错误、无需shell转义）。

Connect

连接

Connect the hosted server with your API key as a Bearer header if you also use runpodctl/flash — that one key auths the MCP and the CLIs (the 80% path):

bash

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

Plain OAuth ("Sign in with Runpod", via

npx @runpod/mcp-server@latest add

) is MCP-only — the CLIs stay unauthed, so use it only for MCP-only work. Local stdio runs the server as a subprocess with your key. Those variants + the key-vs-OAuth tradeoff: reference/connect.md. After connecting, reconnect the client (in Claude Code,

/mcp

) so the tools load.

Verify it's live (do this before relying on MCP): in Claude Code run

/mcp

—

runpod

should show Connected, not Needs authentication (if it's the latter, sign in there first; the bundled plugin server registers the URL but stays inert until you authenticate). Confirm a real call works by asking for

list-endpoints

. If the

runpod

tools aren't present at all, the server isn't connected — (re)run the install above, or fall back to runpodctl for this task.

Check the server version (which REST API it drives): the MCP

initialize

handshake returns it in

serverInfo.version

/mcp

in Claude Code shows it, or probe the hosted server directly:

bash

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 @-

如果您同时使用runpodctl/flash，请使用您的API密钥作为Bearer头连接托管服务器：同一个密钥可同时认证MCP和CLI（这是80%场景的通用方案）：

bash

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

即可查看，或直接探测托管服务器：

bash

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 @-

→ serverInfo.version e.g. "3.0.0 [RUNPOD_REST_VERSION=v2]" (verified 2026-07-29)

→ serverInfo.version 示例："3.0.0 [RUNPOD_REST_VERSION=v2]" （2026-07-29验证）


The MCP server drives Runpod's **REST v2** internally (`RUNPOD_REST_VERSION=v2`), so most
tools avoid the buggy **public `rest.runpod.io/v1`** control API. Two exceptions worth
knowing: the Hub, public-endpoint and `set-endpoint-gpus` tools go through GraphQL (so they
work under either REST version), and **CPU serverless endpoints are not creatable through
MCP** — v2 has no CPU-endpoint concept at all (`create-endpoint` requires `gpuPoolIds`), so
use `runpodctl serverless create --compute-type CPU` for those.

**Prefer MCP or `runpodctl` over hand-rolled `rest.runpod.io/v1` calls for creating endpoints.**


MCP服务器内部驱动Runpod的**REST v2**版本（`RUNPOD_REST_VERSION=v2`），因此大多数工具可避免使用存在bug的**公开`rest.runpod.io/v1`**控制API。有两个值得注意的例外：Hub、公开端点和`set-endpoint-gpus`工具通过GraphQL实现（因此在任一REST版本下均可工作），且**CPU无服务器端点无法通过MCP创建**——v2完全没有CPU端点的概念（`create-endpoint`需要`gpuPoolIds`），因此请使用`runpodctl serverless create --compute-type CPU`创建此类端点。

**对于创建端点，优先使用MCP或`runpodctl`，而非自行编写的`rest.runpod.io/v1`调用。**

Tool surface

工具范围

Structured tools, grouped by resource:

Pods — list, get, create, update, start, stop, restart, delete, stream logs.
Serverless endpoints — list, get, create, update, delete; list workers; list releases; stream worker logs.
- ```
create-endpoint
```
  takes
```
endpointType: QUEUE
```
  (default) or
```
LOAD_BALANCER
```
  — see golden path 14. The routing type is fixed at creation;
```
update-endpoint
```
  cannot change it.
- Read an endpoint's invoke URLs from
```
requestUrls
```
  on the get/list reply instead of assembling them.
- To pin a specific GPU SKU on an existing endpoint use
```
set-endpoint-gpus
```
  ;
```
create-endpoint
```
  /
```
update-endpoint
```
  expose only
```
gpuPoolIds
```
  and can't express a SKU (
```
deploy-hub-repo
```
  can pin one at deploy time via
```
gpuIds
```
  exclusions).
Jobs (serverless runtime) — run, runsync, status, stream, cancel, retry, health, purge queue.
Hub —
```
list-hub-repos
```
(public catalog of prebuilt Serverless workers and Pod templates: vLLM, ComfyUI, …) and
```
deploy-hub-repo
```
, which deploys a repo's listed release as an endpoint — the same as clicking Deploy on the Hub.
Public endpoints —
```
list-public-endpoints
```
: managed pay-per-use model APIs (text/image/video/audio) that need no deployment. Call the returned endpointId with
```
run-endpoint
```
/
```
runsync-endpoint
```
.
Templates — list, get, create, update, delete.
Network volumes — list, get, create, update, delete.
```
create-network-volume
```
takes
```
volumeType
```
(
```
STANDARD
```
|
```
HIGH_PERFORMANCE
```
) and a size of 10–4096 GB; omit
```
volumeType
```
to get the data center's default tier. The tier is immutable after creation —
```
update-network-volume
```
can't change it.
Container registry auth — list, get, create, delete. A username + password for any registry; pass the resulting id as
```
containerRegistryAuthId
```
on create-pod/create-endpoint.
ECR delegations (
```
list-
```
/
```
create-
```
/
```
delete-registry-delegation
```
) — AWS ECR only, v2 only, and stores no credentials: you register a repository ARN and Runpod gets scoped pull access instead. Prefer it over a stored username/password for ECR. The reply carries a
```
dockerRegistryUri
```
— that's the image URI to deploy with.
Catalog — list/get GPU types, list/get CPU types, list/get data centers.
Billing — scoped usage/cost breakdowns (
```
get-billing
```
).

The tool list above is a map, not a contract. The server is the source of truth —
/mcp
(or your client's tool list) shows exactly what the connected version exposes, and each tool carries its own parameter descriptions. Check there before assuming a capability exists or doesn't.

Delete tools (
delete-template
,
delete-pod
, …) can return
isError: true
with "Unexpected end of JSON input" even on success — the Runpod REST API returns 204 No Content. Don't treat it as failure; confirm with a follow-up
get-
/
list-
(a deleted resource then 404s).

结构化工具按资源分组：

Pods——列表、获取、创建、更新、启动、停止、重启、删除、流式传输日志。
无服务器端点——列表、获取、创建、更新、删除；列出工作节点；列出版本；流式传输工作节点日志。
- ```
create-endpoint
```
  接受
```
endpointType: QUEUE
```
  （默认）或
```
LOAD_BALANCER
```
  ——参见黄金路径14。路由类型在创建时固定；
```
update-endpoint
```
  无法更改它。
- 从get/list回复的
```
requestUrls
```
  中读取端点的调用URL，而非自行组装。
- 要在现有端点上固定特定GPU SKU，请使用
```
set-endpoint-gpus
```
  ；
```
create-endpoint
```
  /
```
update-endpoint
```
  仅暴露
```
gpuPoolIds
```
  ，无法指定SKU（
```
deploy-hub-repo
```
  可在部署时通过
```
gpuIds
```
  排除项固定SKU）。
任务（无服务器运行时）——运行、同步运行、状态、流式传输、取消、重试、健康检查、清除队列。
Hub——
```
list-hub-repos
```
（预构建无服务器工作节点和Pod模板的公开目录：vLLM、ComfyUI等）和
```
deploy-hub-repo
```
，用于将仓库的指定版本部署为端点——与在Hub上点击部署操作相同。
公开端点——
```
list-public-endpoints
```
：托管的按使用付费模式API（文本/图像/视频/音频），无需部署。使用
```
run-endpoint
```
/
```
runsync-endpoint
```
调用返回的endpointId。
模板——列表、获取、创建、更新、删除。
网络卷——列表、获取、创建、更新、删除。
```
create-network-volume
```
接受
```
volumeType
```
（
```
STANDARD
```
|
```
HIGH_PERFORMANCE
```
）和10–4096 GB的大小；省略
```
volumeType
```
将使用数据中心的默认层级。层级在创建后不可变——
```
update-network-volume
```
无法更改它。
容器注册表认证——列表、获取、创建、删除。适用于任意注册表的用户名+密码；将生成的id作为
```
containerRegistryAuthId
```
传入create-pod/create-endpoint。
ECR委托（
```
list-
```
/
```
create-
```
/
```
delete-registry-delegation
```
）——仅适用于AWS ECR，仅v2支持，且不存储凭证：您注册仓库ARN，Runpod将获得范围化的拉取权限。对于ECR，优先使用此方式而非存储用户名/密码。回复中包含
```
dockerRegistryUri
```
——这是用于部署的镜像URI。
目录——列出/获取GPU类型、列出/获取CPU类型、列出/获取数据中心。
账单——范围化的使用/成本明细（
```
get-billing
```
）。

上述工具列表是参考而非契约。服务器是权威来源——
/mcp
（或您客户端的工具列表）会准确显示已连接版本暴露的工具，每个工具都带有自己的参数说明。在假设某项功能存在或不存在之前，请先在此处查看。

删除工具（
delete-template
、
delete-pod
等）即使在成功时也可能返回
isError: true
并附带“Unexpected end of JSON input”——这是因为Runpod REST API返回204 No Content。请勿将其视为失败；通过后续的
get-
/
list-
操作确认（已删除的资源会返回404）。

Use MCP vs runpodctl

使用MCP vs runpodctl

Use runpod-mcp when the tools are connected AND the task is infra CRUD or a serverless job call the server exposes. Cap large job/log output to a file.
Use runpodctl instead for: send
/
receive
file transfer, SSH key management, doctor
setup, model cache — or any shell-only agent, or when the user wants a reproducible command.
Hand pod creation to runpodctl for a multi-GPU priority list (MCP's v2 create-pod takes one GPU type; extra
```
gpuTypeIds
```
are dropped with a
```
_warning
```
on success), or for a template + CPU pod together —
```
create-pod
```
rejects that combination, since a template deploy is GPU-and-v2-only. Each alone is fine in MCP:
```
templateId
```
(v2-only,
```
imageName
```
then optional, and each field you pass replaces the template's whole value rather than merging) or
```
computeType: "CPU"
```
.
Not this lane: writing/deploying your own Python (→ flash); downloading models or building/pushing images (→ companion-clis).

For concepts (pods vs serverless, GPU selection, storage), read

../runpod-usage/

使用runpod-mcp：当工具已连接且任务为基础设施CRUD或服务器暴露的无服务器任务调用时。将大型任务/日志输出限制到文件中。
改用runpodctl：用于**
```
send
```
/
```
receive
```
文件传输、SSH密钥管理、
```
doctor
```
**设置、模型缓存——或任何仅支持shell的Agent，或当用户需要可复现的命令时。
将pod创建交给runpodctl：用于多GPU优先级列表（MCP的v2 create-pod仅接受一种GPU类型；额外的
```
gpuTypeIds
```
会在成功时被丢弃并附带
```
_warning
```
），或模板+CPU组合的pod——
```
create-pod
```
会拒绝这种组合，因为模板部署仅支持GPU和v2。单独使用模板或CPU在MCP中是可行的：
```
templateId
```
（仅v2支持，
```
imageName
```
为可选，您传入的每个字段会替换模板的整个值而非合并）或
```
computeType: "CPU"
```
。
不属于此范畴：编写/部署您自己的Python代码（→ flash）；下载模型或构建/推送镜像（→ companion-clis）。

如需了解概念（pod vs 无服务器、GPU选择、存储），请阅读

../runpod-usage/

。

Source & docs

源码与文档

Server source: https://github.com/runpod/runpod-mcp
Package (npm): https://www.npmjs.com/package/@runpod/mcp-server
Hosted endpoint: https://mcp.getrunpod.io/
Docs: https://docs.runpod.io

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