Video sped up for demo purposes

Runway API MCP Server

This repository holds the code for a MCP server that calls the Runway API.

Tools

The following tools are available in this MCP:

Generation tools accept an optional `model` parameter to override the recommended

default. Recommended models: Nano Banana Pro (`gemini_image3_pro`) for images, Seedance

(`seedance2`) for video, and Aleph (`aleph2`) for video editing. Valid `ratio`,

`duration`, and other parameter values are model-specific, so `runway_listModels` returns

the exact valid values and required parameters for every model — call it before choosing a

`ratio`/`duration`.

Before any generation request is sent to the Runway API, the server validates the payload

against OpenAPI-derived per-model constraints (allowed enums, numeric ranges, string

lengths, required fields). Invalid payloads fail locally with a readable error and never

hit the network.

Prerequisites

Before starting, you'll need to have setup your Developer account on the Runway API, setup Billing, and also created an API Key.

You'll also need Node.js setup.

Setup

1. Clone this repository and save it to a folder on your computer. Remember where you saved this folder because you'll need it in a later step.

2. Run `npm install` in the folder, then `npm run build`. You should now see a new folder called `build` with a `index.js` file inside. If you later modify any source files, run `npm run build` again to pick up the changes.

Using the MCP as a Claude Desktop extension (recommended)

This installs the server as an unpacked Claude Desktop extension, so you don't have to edit any config files by hand.

3. Launch Claude Desktop and open Settings.

4. Go to Extensions, then Advanced Settings.

5. Click Install Unpacked Extension and select the folder you cloned in step 1 (for example `/Users/edwin/runway-api-mcp-server`). Click Install on the prompt.

6. Get your API key from https://dev.runwayml.com, paste it into the installed extension's settings, then Enable the extension.

7. Now, try asking Claude to generate an image!

Using the MCP with Claude Desktop (config file)

Alternatively, register the server manually through Claude's config file.

1. Follow the MCP quickstart instructions to setup a config file for Claude. If you already have it, open it by running:

MacOS

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

Windows

notepad %APPDATA%\Claude\claude_desktop_config.json

2. Add the `runway-api-mcp-server` to the config, make sure to replace the file path and Runway API key.

{
  "mcpServers": {
    "runway-api-mcp-server": {
      "command": "node",
      "args": [
        "/build/index.js"
      ],
      "env": {
        "RUNWAYML_API_SECRET": "",
        "MCP_TOOL_TIMEOUT": "1000000"
      }
    }
  }
}

3. Now restart Claude Desktop, and you should see the `runway-api-mcp-server` in Claude's tools:

4. Now, try asking Claude to generate images or videos!

> [!NOTE]

> Images generated by the Runway API lives only for 24 hours at the generated link. There is no way to recover them after this link expires. Make sure to download the images before they expire.

Deploy as a remote MCP server

The same code can run as an HTTP MCP server, which lets clients like

claude.ai web, Cursor, Zed, and Windsurf connect to a

single hosted URL instead of installing the extension locally.

Local HTTP development

RUNWAYML_API_SECRET=key_xxx npm run start:http
# server listens on http://0.0.0.0:3000/mcp
curl http://127.0.0.1:3000/healthz   # → {"ok":true}

To test from web clients (`claude.ai`) without deploying, use a tunnel that

returns HTTPS. Cloudflared works; ngrok is currently blocked by Anthropic's

connector backend:

cloudflared tunnel --url http://127.0.0.1:3000

Use the printed `https://.trycloudflare.com/mcp` as the connector URL.

Deploying to Railway

Railway deploys the HTTP server with zero config.

npm i -g @railway/cli           # one-time
railway login
railway init                    # create a new project, link this folder
railway up                      # builds & deploys
railway domain                  # provisions https://.up.railway.app

Set environment variables in the Railway dashboard (or `railway variables`):

Connect from claude.ai web:

1. Settings → Connectors → Add custom connector

2. URL: `https://.up.railway.app/mcp`

3. Leave OAuth fields blank (Bearer-key flow)

Public deployment auth model

For public, multi-tenant hosting, every user supplies their own Runway API

key:

curl -X POST https://.up.railway.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer " \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

When `REQUIRE_AUTH=true`, requests without a Bearer header receive a 401.

Bearer keys take priority over `RUNWAYML_API_SECRET` even when both are set.