RunPod

Runpod MCP 服务

Runpod 官方 Model Context Protocol（MCP）服务。它可让 Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、opencode 和 Pi 等 MCP 客户端管理你的 Runpod Pods、无服务器端点、模板、网络卷等。

我们已为你托管此服务：https://mcp.runpod.io/——让你的客户端连接到此 URL，然后使用 Runpod 登录。无需安装，也不会在磁盘上存储 API 密钥。你也可以通过 npm 从本地运行它：@runpod/mcp-server。

快速开始

引导式安装程序会检测已安装的客户端，询问你要配置哪些客户端，并为你写入配置：

npx @runpod/mcp-server@latest add

它提供两种连接模式：

• 托管模式（推荐）——让客户端连接到托管服务，并通过“使用 Runpod 登录”（OAuth）进行身份验证。不会在磁盘上存储 API 密钥。
• 本地模式——通过 npx 运行服务，并在客户端配置中存储 RUNPOD_API_KEY。

稍后如需撤销：

npx @runpod/mcp-server@latest remove

若要跳过提示（在脚本、CI 或编码 Agent 的 shell 中使用），请指定客户端名称。支持的 ID 为 claude-code、cursor、windsurf、claude-desktop、vscode、opencode 和 pi：

npx @runpod/mcp-server@latest add --client opencode,pi          # hosted, sign in with Runpod
npx @runpod/mcp-server@latest add --client cursor --local       # local, key read from RUNPOD_API_KEY
npx @runpod/mcp-server@latest remove --client opencode
npx @runpod/mcp-server@latest add --list                        # what's detected, and where each config lives

如果未指定 --client 且没有终端，安装程序会以代码 2 退出，不配置任何内容。使用标志时，如果所有客户端均配置成功，则以代码 0 退出；如果有客户端配置失败，则以代码 1 退出。

或者安装完整的 Runpod 插件

如需完整的 Agent 设置，官方插件市场会将此服务与一个路由技能及另外五个技能捆绑在一起——runpod-mcp、runpodctl、flash、runpod-usage 和 companion-clis：

npx skills add runpod/runpod-plugins-official

该插件适用于 Claude Code、Codex、Cursor、Copilot、Windsurf、Cline、Gemini、opencode 和另外 17 个以上的 Agent，并会安装这些技能——配合上面的 npx @runpod/mcp-server@latest add 使用即可获得控制平面工具。

在 Claude Code 中，原生插件安装方式还会为你配置托管 MCP 服务（包括 OAuth），因此无需单独设置：

/plugin marketplace add runpod/runpod-plugins-official
/plugin install runpod@runpod

要求

• Node.js 20 或更高版本。
• Runpod 账户和 API 密钥。

连接到托管服务

如需手动配置客户端，请让它通过 HTTP 连接到托管服务（无需本地进程，也不会在本地存储 API 密钥）。

Claude Code：

claude mcp add --transport http runpod -s user https://mcp.runpod.io/

其他客户端（Cursor、VS Code、Claude Desktop 连接器等）——使用基于 URL 的 MCP 条目：

{
  "mcpServers": {
    "runpod": {
      "url": "https://mcp.runpod.io/"
    }
  }
}

支持 OAuth 的客户端首次连接时会自动启动“使用 Runpod 登录”流程：客户端会打开浏览器，你登录 Runpod 控制台并批准授权，随后服务会获取一个作用域限定于你当前会话的 Runpod API 密钥。不会在磁盘上存储任何内容。

OAuth 会选择哪个账户？ 生成的密钥对应于你批准授权时浏览器控制台会话中选定的账户或团队资料。如果你属于多个团队，请先在控制台切换到正确的资料（也可以事后检查——工具返回的资源属于该资料）。之后如需更改，请在控制台切换资料，并从 MCP 客户端重新进行身份验证。

更愿意使用自己的 API 密钥而非 OAuth？在 claude mcp add 命令中追加 --header "Authorization: Bearer YOUR_API_KEY"（或在 JSON 中添加 headers 块）。服务会将该密钥直接转发给 Runpod API。

如果使用 HTTP 403 登录失败

如果响应为 403 Forbidden，且标头中包含 X-Vercel-Mitigated: deny，这表示托管服务的防火墙暂时封锁了你的 IP 地址，通常是因为某个 MCP 客户端在短时间内发送了大量未经身份验证的请求。Codex 最常出现这种情况，因为它在登录时会发送许多未经身份验证的请求。封锁适用于所有路径，包括 /register 和携带 API 密钥的请求，并会在一小时内自动解除。等待封锁过期后，使用以下选项之一，避免下次连接再次触发封锁。

你可以按照上文所述，将 API 密钥作为标头发送，而不是使用 OAuth 登录。经过身份验证的请求不会计入限制。在 Codex 中，将密钥添加到 ~/.codex/config.toml 中的服务条目：

[mcp_servers.runpod]
url = "https://mcp.runpod.io/"
bearer_token_env_var = "RUNPOD_API_KEY"

然后在启动 Codex 的 shell 中导出 RUNPOD_API_KEY。

你也可以在本地运行服务。本地服务会直接调用 Runpod API，因此托管防火墙只会影响其 search-docs 工具，该工具仍会通过托管服务进行搜索。

使用情况分析

托管服务会针对每次工具调用（工具名称、状态、耗时、传输方式）和每次指南资源读取（指南 URI；未命中时为 unknown）记录一条匿名事件；此外，在开始阻止 404 循环时，也会记录一条事件（工具名称和阻止时长）。它绝不会记录你的 API 密钥或任何资源数据；除指南和概念工具（list-guides、read-guide、lookup-concept、search-concepts）外，它会丢弃工具参数。对于这些工具，它会保留指南 ID、概念名称或搜索词，以及指南读取类型。你的身份会被转换为不可逆的加盐哈希。若要选择退出，请发送标头 X-Runpod-Analytics: off，例如在 claude mcp add 命令后添加 --header "X-Runpod-Analytics: off"。在本地运行时，不会发送任何数据。

使用 npx 在本地运行

使用你自己的 API 密钥，将服务作为本地 stdio 进程运行：

RUNPOD_API_KEY=YOUR_API_KEY npx -y @runpod/mcp-server@latest

本地客户端设置

本地客户端会启动 stdio 服务，并在环境中设置 RUNPOD_API_KEY。

Claude Code：

claude mcp add runpod -s user \
  -e RUNPOD_API_KEY=YOUR_API_KEY \
  -- npx -y @runpod/mcp-server@latest

项目级服务请使用 -s project。使用 claude mcp list 验证；在会话中，/mcp 可重新连接。

Claude Desktop、Cursor、VS Code、Windsurf 和其他客户端 — 在客户端的 MCP 配置中使用相同的命令：

{
  "mcpServers": {
    "runpod": {
      "command": "npx",
      "args": ["-y", "@runpod/mcp-server@latest"],
      "env": {
        "RUNPOD_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop 的配置文件位于 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）；保存后请重启应用。要查看更完整的客户端列表，请参阅 MCP 客户端目录。

使用示例

用自然语言向 MCP 客户端提问：

List all my Runpod Pods.

Create a Runpod Pod named test-pod with image
runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04,
GPU type NVIDIA GeForce RTX 4090, 1 GPU.

Create a Serverless endpoint named my-endpoint with image
runpod/test-output:0.0.1, GPU pool AMPERE_80, 0 min workers, 3 max workers.

端点基于镜像 — 请传入镜像和 GPU 池（list-gpu-types 返回的 pool 值），而不是模板。

有关主机覆盖设置、私有镜像拉取（注册表凭据与 ECR 委托）以及大输出处理，请参阅 docs/configuration.md。

从 3.x 升级

八个工具遵循其规范中的 operationId（例如， create-container-registry-auth → create-registry，get-billing → list-billing）；而 start-pod/stop-pod/restart-pod 则合并为 pod-action，并使用 action 参数。完整的新旧映射见 specgen/old-mcp-tools.yaml。该服务仅支持 v2；RUNPOD_REST_VERSION 和 v1 回退机制已弃用。

安全

此服务拥有所提供 API 密钥的全部权限。

• 切勿分享你的 API 密钥。
• 谨慎使用具有破坏性的工具。每个工具都带有根据其封装的操作生成的 MCP 注解（readOnlyHint、destructiveHint、idempotentHint、openWorldHint），因此主机可以自动批准读取操作，并要求人工确认 delete-pod 或 purge-endpoint-queue。
• 每个请求都使用调用方提供的独立令牌进行身份验证，该令牌会转发至 Runpod API，绝不会在服务端持久化。服务端不会持有自己的凭据，也不会在用户之间共享凭据。

本地开发

git clone https://github.com/runpod/runpod-mcp.git
cd runpod-mcp
pnpm install
pnpm build

直接运行本地构建：

RUNPOD_API_KEY=YOUR_API_KEY node dist/stdio.mjs

更改后：

pnpm type-check
pnpm lint
pnpm test    # offline unit suite — no network or API key required
pnpm build

工具是根据随项目提供的 v2 OpenAPI 规范生成的，而非手工编写：请参阅 specgen/DESIGN.md 了解操作流程，并参阅 specgen/README.md 了解重新生成工作流和差异检查机制。

工具调用的 REST 客户端 @runpod/typescript-api-sdk 位于 packages/typescript-api-sdk/ 中，并单独发布到 npm。随项目提供的规范位于该包中；SDK 类型和 MCP 工具均由其生成。

本项目使用 changesets 进行版本管理和 npm 发布；每个包含面向用户更改的 PR 都需要附带 changeset。完整的贡献者指南、架构和测试套件请参阅 CLAUDE.md 和 docs/context.md。

许可证

Apache-2.0。packages/typescript-api-sdk/ 中的 SDK 使用 MIT 许可证；请参阅其 LICENSE。

JavaScript API 迁移

此主要版本移除了 @runpod/mcp-server/tools 包导出及其 registerTools API。旧版注册 API 与新的生成接口不兼容。应用应通过 runpod-mcp CLI 使用 MCP 连接到服务，或在嵌入 HTTP 处理程序时使用 @runpod/mcp-server/http 中的 handleMcpRequest。HTTP 入口点也不再重新导出旧版 registerTools 或 ToolContext。

提供目录配置的 HTTP 主机可以从 @runpod/mcp-server/profile 导入 DIRECTORY_PATH 和 profileForPath。