TL;DR: Runware now provides two new entry points into the Runware environment; an MCP server for AI agents, and a CLI for the terminal. Both get you to a working first generation faster than integrating directly, and both reach the same catalog: every major model provider plus thousands of community models, across image, video, audio, 3D, and LLMs, accessible through one interface.
The MCP server: Runware inside your agent
MCP (Model Context Protocol) is an open standard that lets AI agents talk to external services through a defined set of tools. If you're using Claude, Cursor, Codex, VS Code, or any other MCP-compatible client, connecting to the Runware MCP server gives your preferred agent the ability to generate media, search the model catalog, and check pricing without you leaving the session, or writing any integration code.
There are two ways to connect:
Hosted - point your client at https://mcp.runware.ai, paste your Runware API key when prompted, and you're connected. The key is stored server-side, encrypted inside the OAuth session, so your client only ever holds a token, never the key itself.
Local - for agents that can't reach external MCP servers, or restricted and air-gapped networks, you can run the MCP server on a local machine instead:
npx @runware/mcp
Set RUNWARE_API_KEY in your environment and point your client at the local server. The toolset is identical to the hosted version, it just runs on your machine and connects differently.
Either way, your agent gains a set of tools it can call directly.
The MCP Toolbox
Once connected, your agent gains access to a broad set of Runware tools.
The run tool is the core one. It handles image generation, video generation, audio, 3D, LLMs, upscaling, background removal, everything the Runware API supports, through your agent interface. You don't need to tell the agent which task type to use or look up model parameter schemas. You describe what you want, and if you know you want a specific model you can name it; otherwise the agent figures out the best fit for your use case using the catalog tools.
Those catalog tools (list_models, model_details, model_pricing, model_examples) are what give the agent the ability to search and reason about the available models before committing to a generation. This is genuinely useful in various ways; you could ask something like "what does each Veo model cost for an 8-second 1080p clip?" and the agent will use the list_models and model_pricing tools to look up the options and compile a comparison - displayed directly in your agent application.
On pricing: There’s no MCP surcharge. If a generation costs $0.05, you pay $0.05. The browsing and inspection tools are free.
A Practical Example
You're building a product page in a Claude Code session and you need a hero image in a specific aspect ratio. Normally you'd stop, open a separate generation tool, come up with a prompt, iterate on it, download the result, and bring it back to your workspace.
With the Runware MCP integrated into Claude, you can simply ask:
I need a 16:9 banner image for our product page, use Runware, generate two examples for me, one with Nano Banana 2, one with GPT Images 2.0
This example highlights a number of core capabilities;
- One of the requested model names wasn’t found in the Runware model catalogue, so the MCP model search tool was employed by the agent to locate it.
- One of the generation requests returned an error and was automatically retried.
- The agent used the
ToolSearchcapability to look up the correct schema for the model, identifying acceptable dimensions to solve the issue.
With two sample images generated, Claude Code then offers to wire one into the project, adding it to the repository, all from within the coding agent app - no context-switching required.
The CLI: Runware from your terminal
The CLI is a separate tool, a native runware binary that you install on your machine. It's built for working directly without an agent in the loop: generating from the terminal, scripting, testing models, and dropping generation into automated pipelines. The CLI is fully open source and released under the MIT License, so you can inspect the source, build it yourself, and review exactly what you're installing. The source code is available on the Runware GitHub: https://github.com/Runware/runware-cli/tree/main
The core command is runware run:
runware run runware:101@1 positivePrompt="a chess match in the park" width=1024 height=1024
Results download automatically to an ./outputs folder.
The same run command works for video, audio, 3D, and text inference, just swap the model identifier. The CLI fetches the model's schema automatically and validates your parameters before the job runs, so you find out about mistakes before any spend.
Beyond generation, the CLI can search the model catalog, check pricing, inspect a model's full parameter schema, and manage presets for configurations you run often. Output supports --format json for piping into other tools or scripts, making it practical for automation.
Search models
runware model search -q "flux"
Check a model's parameters before running
runware model schema runware:101@1 --format json
Check your account and usage across your API keys
runware account details --format JSON
Like the MCP Server, browsing and inspection calls via the CLI are free. There’s no additional fee to access Runware’s services via CLI.
CLI or MCP: which one do you need?
The MCP server is the right choice when you're already working inside an agent. You describe what you want, the agent handles the tool calls, and generation happens inside the conversation. It's particularly useful when you want the agent to figure out model selection, chain calls across modalities, or work media generation into a bigger task.
The CLI is the right choice when you want to work directly, without an agent. Unlike the MCP, it isn't conversational; you need to know which command to run and what parameters to pass, rather than describing what you want in plain language. That's a reasonable tradeoff when the task is well-defined: scripting a batch job, running generations in CI/CD, or just generating something quickly from a terminal window without spinning up an agent session.
Getting started
Hosted MCP (Claude, Cursor, VS Code, and most other clients):
Add https://mcp.runware.ai as a custom MCP server in your client's settings and complete the OAuth flow when prompted. You'll paste your Runware API key into a Runware-branded page - that's the only time your API key is ever visible.
Local MCP server:
npx @runware/mcp
Set RUNWARE_API_KEY in your environment and point your client at the local server.
The landing page with per-client MCP setup information is at runware.ai/mcp.
CLI:
macOS:
brew tap runware/tap
brew install runware
Windows (via Scoop):
scoop bucket add runware https://github.com/Runware/scoop-bucket.git
scoop install runware
Linux:
curl -fsSL https://cli.runware.ai/install.sh | sh
Then authenticate on any platform with your API key:
runware auth login
Once authenticated, run runware ping to confirm connectivity, and you're ready.
Full CLI reference at github.com/Runware/runware-cli.
The landing page with per-client CLI setup information is at runware.ai/cli.
FAQ
What's the difference between the MCP and the CLI?
The MCP is conversational; you describe what you want and the agent handles the model selection, parameters, and tool calls. The CLI is direct; you write the commands yourself, which makes it better suited to scripting, automation, and situations where you don't want an agent in the loop. Both provide access to the same tools and models.
What platforms does the CLI support?
macOS, Windows, and Linux. macOS via Homebrew, Windows via Scoop, Linux via a shell installer.
Can I build from source?
Yes. Clone the repo and run make build. The full steps are in the docs.
Do I need a Runware account to use either?
Yes, both require a free Runware API key. You can create an account and generate an API key at runware.ai
Can I use both CLI and MCP?
Yes. They can share the same API key, linking to the same account balance, and the same model catalog, or be set up with different keys, depending on your needs. Use the MCP when you're working with an agent, and the CLI when you're in a terminal or a script.
WebSocket or REST?
It's WebSocket by default, but you can switch with --transport http.
Top comments (0)