A woman looks down at a glowing light bulb in her hands while the orange Claude Code mascot sits on her shoulder.

How to build a generative media integration with Claude Code

Summary

Claude Code can build, debug and maintain a video, image, audio or real-time avatar generation integration end to end.

Install the Runway Dev plugin and Claude Code gets the Runway Dev MCP, which reads your Runway Dev account and the live model catalog, plus seven Runway Dev skills for building with the API.

You can also connect the Runway Dev MCP and install the skills yourself from the terminal.

This article covers the plugin install, sign-in, your API key and the first build.

With the plugin installed, Claude Code picks models against current prices and input limits, configures whatever the integration needs and reads back the actual cause when a generation fails.

Claude Code with the Runway Dev plugin: it builds the site, routes product shots through a Model Router, fixes a failed task and checks your balance.

Step 1: Install the Runway Dev plugin in Claude Code

Run these commands in a terminal:

claude plugin marketplace add anthropics/claude-plugins-official
claude plugin install runway-api@claude-plugins-official
claude mcp login plugin:runway-api:runway-dev

The first command adds Anthropic’s official plugin marketplace, which Claude Code also adds on its own the first time you start an interactive session. The second installs the plugin, listed as Runway Dev in Anthropic’s plugin directory. The third opens your browser to sign in to your Runway Dev account. On Claude Code versions older than 2.1.186, run /mcp in a session instead and select the Runway Dev server. Start a new session to use the plugin.

Inside a session, /plugin install runway-api@claude-plugins-official installs it too, and the same steps work in the Code tab of the Claude desktop app. The Runway Dev plugin guide keeps the current commands.

The Runway Dev plugin bundles two parts:

  • The Runway Dev MCP, at https://dev.runwayml.com/mcp/claude. It lets Claude Code read the projects on your account, the models each one can call with their prices and input limits, your credit balance, your Model Routers, your Characters and the record behind any task. New Characters are created in your Runway Dev account.
  • Seven Runway Dev skills: runway-dev-setup, runway-dev, runway-dev-models, runway-dev-model-routers, runway-dev-characters, runway-dev-recipes and runway-dev-workflows. They show Claude Code how to integrate the API with the official SDKs before it writes anything.

Complete the sign-in yourself rather than asking Claude Code to automate it. No API key goes into the plugin: the connection is OAuth, and your keys stay in your Runway Dev account.

Confirm it worked. Ask which Runway Dev account it is connected to and how many credits you have. It should return the email on your Runway Dev account and your current balance.

If you’re using Claude Code from the desktop app: start from Quickstart

Open Quickstart in Runway Dev and click Open in Claude Code. It opens a new session carrying a prompt that points at Runway Dev’s setup brief, and the agent works from there: it inspects your project, reads the documentation and installs the Runway Dev plugin from the plugin guide. Approve the sign-in in your browser when it asks.

The Runway Dev dashboard with the Quickstart button highlighted, next to the options to open in Codex, Claude Code or Cursor, or copy as Markdown

That button is an app deep link, so it only works if you have the desktop app. From the terminal, use the commands above, or use Copy prompt in Quickstart and paste it into Claude Code.

Or connect the Runway Dev MCP and the skills yourself

The same two parts can be set up one at a time. Use one route only: with the plugin installed, this would give Claude Code a second copy of each.

claude mcp add --transport http --scope user runway-dev-mcp https://dev.runwayml.com/mcp/claude
claude mcp login runway-dev-mcp
npx skills add runwayml/skills --skill runway-dev-setup --skill runway-dev --skill runway-dev-models -a claude-code -y

--scope user makes the server available in every project. Use --scope project instead if you only want it in the current one. On Claude Code 2.1.191 and newer, add --no-browser to the login command to print an authorization URL rather than opening a local browser, which is what you want on a remote machine or over SSH. Both version thresholds are documented in the Runway Dev MCP setup guide.

Add the skill for what you are building: runway-dev-models, runway-dev-model-routers, runway-dev-characters, runway-dev-recipes or runway-dev-workflows. runway-dev-setup and runway-dev come along every time.

If Claude Code shows “Needs authentication”: run /mcp, select the Runway Dev server, complete the sign-in in your normal browser, then retry the tool in the same session. Only start a new session if the authenticated tools are still unavailable.

Step 2: Add your API key to the project

The MCP connection is OAuth, but a live generation call still needs a key of its own. The first time Claude Code is ready to run something, it asks for RUNWAYML_API_SECRET in the project environment.

Create the key in your Runway Dev account and add it to the project’s environment file yourself. Do not paste it into the session, and do not let it end up hardcoded: Claude Code reads it from the environment.

Step 3: Describe what you are building

Claude Code now has your codebase, your account and the live catalog, so it does not need to be told which endpoint to call. It needs to know what you are building.

  • Say what someone using your product should be able to do.
  • Name what you already have as input: a product photo for image to video, a script for text to video, a catalog feed.
  • Name what you need out: duration, resolution, format, whether it needs audio.
  • Say where it runs: a route in your web app, a background job, a nightly batch.
  • Give your constraints: a ceiling per generation, how long a user will wait, the quality bar you are holding.
  • Ask it to explain which Runway Dev surface it plans to use, and why, before it writes any code.

Runway Dev offers more than a generation endpoint, and the right surface depends on the job:

  • A Model Router, when you want the best model for each request without evaluating models yourself. Your code passes a config ID instead of a model name, and Claude Code can create the router and rewrite the calling code in the same turn.
  • A Recipe, when Runway has already built and tuned the use case. One call returns a production-ready asset, with the model selection, prompting and chaining already done.
  • A custom Workflow, when the pipeline is specific to you and takes several steps. It is built visually in the Runway Creative App, then published as an endpoint your integration calls once.
  • A model called directly, when you already know which one you want.

When a generation fails, Claude Code looks the task up itself and reads the actual cause, whether that is a moderation rejection, an asset over a size limit or a malformed request body, rather than working backwards from a status code.

You are now ready to let Claude Code handle media generation with Runway Dev autonomously, end to end.

Install the Runway Dev plugin in Claude Code and describe your first feature. Create an account to start building.

FAQ

How do I connect Claude Code to Runway Dev?

Install the Runway Dev plugin: run claude plugin marketplace add anthropics/claude-plugins-official, then claude plugin install runway-api@claude-plugins-official, then claude mcp login plugin:runway-api:runway-dev to sign in to your Runway Dev account in the browser. Start a new session to use it.

What does the Runway Dev plugin for Claude Code include?

The Runway Dev MCP at https://dev.runwayml.com/mcp/claude, which reads your Runway Dev account and the live model catalog, and seven Runway Dev skills covering setup, the SDKs, models, Model Routers, Characters, Recipes and Workflows.

How do I connect Runway Dev to Claude Code in the desktop app?

Run the same plugin commands in the Code tab, or open Quickstart in Runway Dev and click Open in Claude Code. Quickstart opens a new session with a prompt pointing at Runway Dev’s setup brief, and the agent installs the Runway Dev plugin from there. Approve the sign-in in your browser when it asks.

Does Claude Code use the same setup as Claude Desktop?

No. Claude Code installs the Runway Dev plugin from a terminal. Claude Desktop chat installs Runway Dev from the plugin directory for the skills and adds https://dev.runwayml.com/mcp/claude as a custom connector, since Claude Code does not use Claude Desktop connectors.

Can I log in to Runway Dev MCP from the Claude Code terminal?

Yes, on Claude Code 2.1.186 and newer. With the plugin, run claude mcp login plugin:runway-api:runway-dev; with a server added by hand, run claude mcp login runway-dev-mcp. Version 2.1.191 adds --no-browser, which prints an authorization URL instead of opening a local browser.

How do I connect Runway Dev MCP over SSH or on a remote machine?

Use claude mcp login plugin:runway-api:runway-dev --no-browser on Claude Code 2.1.191 or newer, or runway-dev-mcp in place of the plugin’s server name if you added the server by hand. It prints an authorization URL you can open on whichever machine has a browser.

Why does Claude Code say “Needs authentication” for Runway Dev?

The server is added but the OAuth sign-in has not completed. Run /mcp, select the Runway Dev server, finish the sign-in in your normal browser, then retry the tool in the same session. Start a new session only if the authenticated tools are still unavailable.

Should I install Runway Dev with --scope user or --scope project?

Use --scope user, the default for claude plugin install, to make Runway Dev available in every project on that machine, and --scope project to limit it to the current one. claude mcp add takes the same two scopes.

How do I update the Runway Dev plugin in Claude Code?

Run claude plugin marketplace update claude-plugins-official, then claude plugin update runway-api@claude-plugins-official -y, and restart Claude Code.

Do I put my Runway API key in the Claude Code plugin or MCP config?

No. The connection uses OAuth in the browser, so no key belongs in the plugin or any MCP config. Keys stay in your Runway Dev account, where you can rotate them.

Do I still need a Runway API key with Claude Code?

Yes, for live generation calls from your app. Claude Code asks for RUNWAYML_API_SECRET in the project environment the first time it is ready to run something. Add it yourself rather than pasting it into the session.

How do I know Claude Code is connected to Runway Dev?

Ask who you are and how many credits you have. It returns the email on your Runway Dev account and your current credit balance.

Does the Open in Claude Code button in Quickstart work from the terminal?

No. The Quickstart buttons are app deep links, so they hand off to the desktop app. If you work in the terminal, use Copy prompt in Quickstart and paste the prompt into Claude Code instead.

Are there Runway Dev skills for Claude Code?

Yes, seven, and the Runway Dev plugin installs all of them. To install them without the plugin, run npx skills add runwayml/skills --skill runway-dev-setup --skill runway-dev --skill <surface-skill> -a claude-code -y. The surface skills cover models, Model Routers, Characters, Recipes and Workflows.

Can Claude Code create a Model Router for me?

Yes. Ask for a router with the settings you want and for the integration to be updated to use it. It creates the configuration, reads it back, and rewrites the calling code to pass the config ID.

Can Claude Code spend my credits without asking?

No. Runway Dev’s setup brief tells the agent to treat a billable test call as optional unless you asked for one, and to ask before creating or changing anything live in the account.

How does Claude Code debug a failed generation?

It looks the task up through the MCP and reads the recorded cause, such as a moderation rejection, an asset over a size limit or a malformed request body, instead of guessing from the error string.

What can I build with Claude Code and Runway Dev?

Video, image and audio generation, real-time conversational video agents through Characters, upscaling and HDR output, using models from Runway and from other frontier labs.

Start building on Runway Dev