| name | runpod-mcp |
| description | Manage Runpod infrastructure — pods, serverless endpoints, jobs, templates, network volumes, container-registry auth, GPU/CPU catalog, and billing — via the Runpod MCP server's structured tool calls. Use when the Runpod MCP tools (create-pod, list-endpoints, …) are connected in this session, or to connect them (hosted OAuth or local npx). Prefer this over runpodctl for plain infra CRUD when MCP is available; use runpodctl for the terminal, Hub deploys, file transfer, or SSH setup. |
| allowed-tools | Bash(npx:*), Bash(claude:*) |
| compatibility | Linux, macOS, Windows |
| metadata | {"author":"runpod","version":"1.1.0"} |
| license | Apache-2.0 |
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).
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):
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:
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 @-
The MCP server drives Runpod's REST v2 internally (RUNPOD_REST_VERSION=v2), so it
handles infra correctly where the public rest.runpod.io/v1 control API is buggy —
notably CPU serverless endpoints (see the runpodctl skill).
Prefer MCP or runpodctl over hand-rolled rest.runpod.io/v1 calls for creating endpoints.
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.
- Jobs (serverless runtime) — run, runsync, status, stream, cancel, retry, health, purge queue.
- Templates — list, get, create, update, delete.
- Network volumes — list, get, create, update, delete. ⚠️
create-network-volume takes only name/size/dataCenter — it can't set the storage tier, so it always gets the data center's default. For a High-Performance volume use the console or a raw v2 REST call (POST https://v2-rest.runpod.io/v2/network-volumes with "type":"HIGH_PERFORMANCE"); see golden path 21.
- Container registry auth — list, get, create, delete.
- Catalog — list/get GPU types, list/get CPU types, list/get data centers.
- Tags — list, get, create, update, delete; attach/detach to resources.
- Billing — scoped usage/cost breakdowns (
get-billing).
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).
Use 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: anything MCP has no tool for — Hub
browse/deploy,
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 when it needs a capability MCP's create-pod
lacks: from a template (
--template-id), a CPU pod (--compute-type cpu), or a multi-GPU priority list. MCP's v2 create-pod requires an image
and takes a single GPU type — fine for a simple one-image/one-GPU pod, but defer
the richer cases even when MCP is connected.
- 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/.
Source & docs
