RunPod MCP Server

Runpod MCP server

This is the official Runpod Model Context Protocol (MCP) server, published to npm as @runpod/mcp-server.

It supports two deployment modes:

• Local stdio for Claude Desktop, Claude Code, Cursor, VS Code, and other MCP clients that launch a local process. The caller sets RUNPOD_API_KEY in the environment.
• Hosted Streamable HTTP for Vercel or other HTTP-capable platforms. Each request carries its own Authorization: Bearer <token>, which the server forwards directly to the Runpod API. The token can be a Runpod API key or one obtained through the OAuth "Sign in with Runpod" flow.

The server never holds a credential of its own and never shares one across users.

Requirements

• Node.js 18 or higher.
• A Runpod account and API key: https://www.runpod.io/console/user/settings

Quick start

Run locally with npx

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

Install via Smithery

npx -y @smithery/cli install @runpod/runpod-mcp-ts --client claude

Local MCP clients

Local MCP clients should use the default package entrypoint, which is the stdio server.

Claude Code

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

For a project-local server:

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

Verify with claude mcp list. In an active session, use /mcp to reconnect.

Claude Desktop

Local MCP servers in Claude Desktop still use claude_desktop_config.json.

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\\Claude\\claude_desktop_config.json

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

Restart Claude Desktop after saving.

Cursor

Add this to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

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

VS Code, Windsurf, Cline, JetBrains, and other local clients

Use the same pattern:

• command: npx
• args: ["-y", "@runpod/mcp-server@latest"]
• env: RUNPOD_API_KEY=YOUR_API_KEY

For a broader list of MCP clients, see https://modelcontextprotocol.io/clients

Hosted HTTP deployment

The package also exports a Streamable HTTP entrypoint at @runpod/mcp-server/http, and this repo includes a Vercel function in api/index.ts.

The hosted transport is stateless:

• Each request creates a fresh MCP server instance.
• The caller must send Authorization: Bearer <token>.
• No credentials are cached or shared server-side.

Hosted auth

The server forwards the caller's Bearer token directly to the Runpod API as the credential for that request. There is no server-side or shared key.

The token can be either:

• a Runpod API key the caller configured manually, or
• a Runpod API key obtained through the OAuth "Sign in with Runpod" flow (see below).

An unauthenticated request receives a 401 with a WWW-Authenticate header pointing at the protected-resource metadata, which tells an OAuth-capable client (such as Claude) to start the sign-in flow. A caller that brings its own API key as the bearer token never hits that path.

Sign in with Runpod (authorize flow)

In OAuth mode the hosted server is itself the authorization server for Claude's connector. It advertises itself in /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server, pointing authorization_endpoint at its own GET /authorize, token_endpoint at its own POST /token, and registration_endpoint at its own POST /register.

The flow reuses the Runpod flash auth backend and mints a real Runpod API key:

1. The client registers via POST /register (OAuth Dynamic Client Registration, RFC 7591) to obtain a client_id. This is a public client; no client secret is used.
2. GET /authorize calls the guest createFlashAuthRequest mutation to get a request id (which serves as the OAuth authorization code), then 302-redirects the browser to the console handoff page (/integrations/mcp/login), carrying the request id plus the client's redirect_uri and state.
3. The user logs in and approves the request in the console. On approval the backend mints a Runpod API key for the request.
4. The console returns the browser to the client's redirect_uri with code=<request id>.
5. POST /token polls the guest flashAuthRequestStatus query for that id; once APPROVED, it returns the minted apiKey as the access_token. The client then sends that key as its bearer token on every MCP request, and the server forwards it to the Runpod API.

This flow uses these environment variables:

• RUNPOD_GRAPHQL_URL: flash auth backend endpoint (default https://api.runpod.io/graphql).
• CONSOLE_BASE_URL: base URL of the console that hosts the handoff login page (default https://console.runpod.io).
• RUNPOD_REST_API_URL / RUNPOD_SERVERLESS_API_URL: override the REST and Serverless API hosts so a deployment authenticating with non-production keys can target the matching environment.
• RUNPOD_API_KEY_NAME: name for the minted key as shown in the user's dashboard. Defaults to runpod-mcp. Set it to "" to omit the name for a backend that does not support the apiKeyName argument (such backends reject the request when it is sent).
• MCP_ALLOWED_REDIRECT_URIS: comma-separated extra redirect_uri values to allow, in addition to the built-in Claude callbacks. Loopback addresses (localhost/127.0.0.1/::1, any port) are always allowed. /authorize and /token reject any redirect_uri not on this list, since the authorization code redeems into a real API key.

You can verify the entire flow end to end with MCP_SERVER_URL=<deployment-url> npx tsx scripts/oauth-e2e.ts (the harness uses a loopback callback).

Notes and current limitations:

• PKCE is not supported: code_challenge is neither advertised nor enforced (the flash flow has no place to bind it). Security relies on the redirect_uri allowlist and the single-use, short-lived flash approval.
• The minted key is named via RUNPOD_API_KEY_NAME (default runpod-mcp), which requires a flash backend that supports the apiKeyName argument. Against a backend without it, set RUNPOD_API_KEY_NAME="".

Vercel

This repo already contains vercel.json and the Vercel handler.

Deploy with the Vercel CLI:

vercel
vercel --prod

After deploy, test the endpoint:

curl -i https://YOUR-DEPLOYMENT.vercel.app/

Unauthenticated requests should return 401.

Hosted smoke test

MCP_SERVER_URL=https://YOUR-DEPLOYMENT.vercel.app \
RUNPOD_API_KEY=YOUR_API_KEY \
pnpm smoke:http

This validates:

• MCP initialization.
• tools/list.
• A public GraphQL-backed tool call.
• An authenticated REST-backed tool call.

Claude Desktop and hosted MCP

Use the local stdio integration for Claude Desktop today.

For remote clients such as Claude's connector, deploy the hosted HTTP server. The client then runs the OAuth "Sign in with Runpod" flow, and the resulting Runpod API key is forwarded to the Runpod API on each request.

Local development

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

Run the local build directly:

RUNPOD_API_KEY=YOUR_API_KEY node dist/stdio.mjs

Or point a client at your local build:

{
  "command": "node",
  "args": ["/absolute/path/to/runpod-mcp/dist/stdio.mjs"],
  "env": {
    "RUNPOD_API_KEY": "YOUR_API_KEY"
  }
}

Local smoke test

RUNPOD_API_KEY=YOUR_API_KEY pnpm build
RUNPOD_API_KEY=YOUR_API_KEY pnpm smoke:stdio

Usage examples

List all Pods

Can you list all my Runpod Pods?

Create a new Pod

Create a new Runpod Pod with the following specifications:
- Name: test-pod
- Image: runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04
- GPU Type: NVIDIA GeForce RTX 4090
- GPU Count: 1

Create a Serverless endpoint

Create a Runpod Serverless endpoint with the following configuration:
- Name: my-endpoint
- Template ID: 30zmvf89kd
- Minimum workers: 0
- Maximum workers: 3

Contributing

The source is now split by responsibility:

• src/stdio.ts: local stdio entrypoint.
• src/http.ts: bearer-token extraction and the per-request MCP session for the Streamable HTTP transport.
• src/tools.ts: all Runpod MCP tools.
• src/server.ts: shared server metadata and construction.
• api/index.ts: Vercel adapter and the OAuth authorization-server routes (/.well-known/*, /register, /authorize, /token).

After changes:

pnpm type-check
pnpm lint
pnpm build

For transport validation:

pnpm smoke:stdio
pnpm smoke:http

This project uses changesets for versioning and npm publishing. Every PR with user-facing changes needs a changeset file at .changeset/DESCRIPTIVE_NAME.md.

See CLAUDE.md and docs/context.md for contributor guidance.

Security considerations

This server acts with the full permissions of the supplied RUNPOD_API_KEY.

• Never share your API key.
• Be deliberate about destructive tools.
• Treat hosted deployments as sensitive infrastructure.
• Each request authenticates with its own caller-supplied token, which is forwarded to the Runpod API and never persisted server-side.

License

Apache-2.0