runway_listModelsLABSCO SUMMARY
Generation calls that fail on your machine instead of failing at Runway.
Ratios, durations and required fields differ from model to model, and the awkward part of driving a generation API from an agent is that the model guesses them. Here runway_listModels returns the exact valid values for each, and every payload is checked against the OpenAPI-derived constraints before it goes out, so a wrong enum comes back as a readable local error rather than a spent request. The output links expire after 24 hours and nothing recovers them, so treat downloading as part of the job.
What it is
A client for Runway's generation API: video from an image and a prompt, images from a prompt with references, video upscaling and prompt-based editing, plus the task polling and credit balance around them.
What you get
- Video generated from an image and a text prompt, at one of the ratios the chosen model accepts
- Images generated from a prompt, optionally guided by reference images — previously generated ones or URLs, since uploads do not work as references
- Video upscaled to a higher resolution from a URL or a data URI
- Video edited from a text prompt, with reference images, through Aleph
- Spoken audio generated from text, with a voice option
- The models available per capability with the recommended default for each, and the exact valid ratio, duration and required parameters for every one of them
- Payloads validated locally against per-model constraints derived from the OpenAPI spec — allowed enums, numeric ranges, string lengths, required fields — so an invalid request fails readably without reaching the network
- Task status polled until it succeeds and carries a url, or fails and carries an error, and tasks cancelled
- The organisation's credit balance and usage details
Requirements
A Runway developer account with billing set up and an API key, passed as RUNWAYML_API_SECRET. Node.js, then npm install and npm run build in the clone; the tidiest path is installing that folder as an unpacked Claude Desktop extension and pasting the key into its settings rather than editing config by hand. Generations run long enough that the documented Claude Desktop config sets MCP_TOOL_TIMEOUT explicitly. The same code runs as an HTTP server for remote clients, where REQUIRE_AUTH=true makes each user send their own key as a bearer token and a request without one gets a 401. Plan for one thing: generated images live at their returned link for 24 hours and cannot be recovered afterwards, so download them.
Setup effort
Build from source — git clone https://github.com/runwayml/runway-api-mcp-server.git
USE CASES
01
Turning a still into a clip
Check the model's valid ratio and duration first, then generate the video from the image and prompt and poll for the result.
02
Generating an image to work from
Generate from the prompt, guiding it with URLs or previously generated images as references.
03
Changing something in a video you already have
Edit it from a text prompt with reference images rather than regenerating from scratch.
04
Getting a clip up to delivery resolution
Upscale the video from its URL or data URI.
05
Adding a voice track
Generate the spoken audio from the script text with the voice you want.
06
Not overspending on generations
Read the organisation's credit balance and usage, and cancel a task you no longer need.
9 tools
Listed in project docs. Your client may show a different list.
runway_generateVideorunway_generateImagerunway_upscaleVideorunway_editVideorunway_generateAudiorunway_getTaskrunway_cancelTaskrunway_getOrgBEFORE YOU INSTALL
What to know first
Tools you get
9 tools named in the project's documentation. The npm package runway-api-mcp-server (1.0.0) has seven of them, without runway_listModels and runway_generateAudio, so build from a current clone with npm run build to get all nine; runway_listModels gives the valid ratios and durations per model.
Requires
- Node.js
- RUNWAYML_API_SECRET in your environment
INSTALLATION
Connect your client
Server setup
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.
TERMINAL
git clone https://github.com/runwayml/runway-api-mcp-server.git
cd runway-api-mcp-server
npm install
npm run buildYou should now see a new folder called build with a index.js file inside.
MCP Clients
Claude Desktop — extension
Launch Claude Desktop and open Settings.
Go to Extensions, then Advanced Settings.
Click Install Unpacked Extension and select the folder you cloned in step 1. Click Install on the prompt.
Get your API key from https://dev.runwayml.com, paste it into the installed extension's settings, then Enable the extension.
Claude Desktop — local build
CLAUDE DESKTOP — LOCAL BUILD · JSON
{
"mcpServers": {
"runway-api-mcp-server": {
"command": "node",
"args": [
"<YOUR_CLONED_REPO_STEP>/build/index.js"
],
"env": {
"RUNWAYML_API_SECRET": "<YOUR_RUNWAYML_API_SECRET>",
"MCP_TOOL_TIMEOUT": "1000000"
}
}
}
}Claude.ai — self-hosted
From your clone, deploy the HTTP server to Railway: npm i -g @railway/cli, then railway login, railway init, railway up, and railway domain (provisions https://<YOUR_APP>.up.railway.app)
Set environment variables in the Railway dashboard (or railway variables): RUNWAYML_API_SECRET and REQUIRE_AUTH, as the README's variable table describes
In claude.ai: Settings → Connectors → Add custom connector
Enter https://<YOUR_APP>.up.railway.app/mcp as the connector URL
Leave OAuth fields blank (Bearer-key flow)
