TL;DR: Runware는 이제 Runware 환경으로 들어가는 두 가지 새로운 진입점을 제공합니다. AI 에이전트를 위한 MCP 서버와 터미널을 위한 CLI가 그것입니다. 두 방식 모두 직접 통합하는 것보다 더 빠르게 첫 번째 결과물을 생성할 수 있게 해주며, 이미지, 비디오, 오디오, 3D, 그리고 LLM(대규모 언어 모델)에 이르기까지 하나의 인터페이스를 통해 접근 가능한 모든 주요 모델 제공업체와 수천 개의 커뮤니티 모델을 포함하는 동일한 카탈로그에 도달합니다.

MCP 서버: 에이전트 내부의 Runware

MCP (Model Context Protocol)는 AI 에이전트가 정의된 도구 세트를 통해 외부 서비스와 통신할 수 있게 해주는 개방형 표준입니다. Claude, Cursor, Codex, VS Code 또는 기타 MCP 호환 클라이언트를 사용 중이라면, Runware MCP 서버에 연결함으로써 사용자가 세션을 떠나거나 별도의 통합 코드를 작성하지 않고도 선호하는 에이전트가 미디어를 생성하고, 모델 카탈로그를 검색하며, 가격을 확인할 수 있는 능력을 부여할 수 있습니다.

연결하는 방법에는 두 가지가 있습니다:

Hosted (호스팅 방식) - 클라이언트를 https://mcp.runware.ai로 지정하고, 요청 시 Runware API 키를 붙여넣으면 연결됩니다. 키는 서버 측에 저장되며 OAuth 세션 내에서 암호화되므로, 클라이언트는 토큰만 보유할 뿐 키 자체는 절대 보유하지 않습니다.

Local (로컬 방식) - 외부 MCP 서버에 접속할 수 없는 에이전트나 제한된 폐쇄망(air-gapped networks)의 경우, 대신 로컬 머신에서 MCP 서버를 실행할 수 있습니다:

npx @runware/mcp

환경 변수에 RUNWARE_API_KEY를 설정하고 클라이언트를 로컬 서버로 지정하세요. 도구 세트는 호스팅 버전과 동일하며, 단지 사용자의 머신에서 실행되고 다르게 연결될 뿐입니다.

어떤 방식이든, 여러분의 에이전트는 직접 호출할 수 있는 도구 세트를 얻게 됩니다.

MCP Toolbox

연결되면 에이전트는 광범위한 Runware 도구 세트에 대한 액세스 권한을 얻습니다.

run 도구가 핵심입니다. 이 도구는 에이전트 인터페이스를 통해 이미지 생성 (image generation), 비디오 생성 (video generation), 오디오 (audio), 3D, LLM, 업스케일링 (upscaling), 배경 제거 (background removal) 등 Runware API가 지원하는 모든 기능을 처리합니다. 에이전트에게 어떤 작업 유형 (task type)을 사용할지 알려주거나 모델 파라미터 스키마 (model parameter schemas)를 찾아볼 필요가 없습니다. 여러분은 원하는 것을 설명하기만 하면 됩니다. 특정 모델을 사용하고 싶다면 이름을 지정할 수도 있고, 그렇지 않다면 에이전트가 카탈로그 도구 (catalog tools)를 사용하여 사용 사례에 가장 적합한 모델을 찾아냅니다.

해당 카탈로그 도구들(list_models, model_details, model_pricing, model_examples)은 에이전트가 생성을 실행하기 전에 사용 가능한 모델을 검색하고 추론할 수 있는 능력을 부여합니다. 이는 여러 방면에서 진정으로 유용합니다. 예를 들어, "각 Veo 모델의 8초 1080p 클립당 비용은 얼마인가요?"와 같이 질문하면, 에이전트는 list_models와 model_pricing 도구를 사용하여 옵션을 찾아보고 비교표를 작성하여 여러분의 에이전트 애플리케이션에 직접 표시해 줍니다.

가격에 대하여: MCP 추가 요금은 없습니다. 생성 비용이 $0.05라면, 여러분은 $0.05만 지불하면 됩니다. 브라우징 (browsing) 및 조사 (inspection) 도구는 무료입니다.

실용적인 예시

여러분은 Claude Code 세션에서 제품 페이지를 구축하고 있으며, 특정 종횡비 (aspect ratio)를 가진 히어로 이미지 (hero image)가 필요합니다. 보통은 작업을 멈추고, 별도의 생성 도구를 열고, 프롬프트 (prompt)를 구상하고, 이를 반복하며, 결과물을 다운로드하여 작업 공간으로 다시 가져와야 합니다.

Runware MCP가 Claude에 통합되어 있으면, 다음과 같이 간단히 요청할 수 있습니다:

우리 제품 페이지에 사용할 16:9 배너 이미지가 필요해. Runware를 사용해서 Nano Banana 2를 사용한 예시 하나와 GPT Images 2.0을 사용한 예시 하나, 총 두 개를 생성해줘.

이 예시는 여러 핵심 역량을 강조합니다;

• 요청된 모델 이름 중 하나가 Runware 모델 카탈로그(model catalogue)에서 발견되지 않아, 에이전트가 이를 찾기 위해 MCP 모델 검색 도구(model search tool)를 사용했습니다.
• 생성 요청 중 하나가 오류를 반환하여 자동으로 재시도되었습니다.
• 에이전트는 ToolSearch 기능을 사용하여 해당 모델에 대한 올바른 스키마(schema)를 조회하였고, 문제를 해결하기 위해 허용 가능한 차원(dimensions)을 식별했습니다.

두 개의 샘플 이미지가 생성되면, Claude Code는 이를 프로젝트에 연결하여 저장소(repository)에 추가할 것을 제안합니다. 이 모든 과정은 코딩 에이전트 앱 내에서 이루어지므로 컨텍스트 스위칭(context-switching)이 필요하지 않습니다.

CLI: 터미널에서 사용하는 Runware

CLI는 별도의 도구로, 사용자의 머신에 설치하는 네이티브 runware 바이너리입니다. 이는 에이전트의 개입 없이 직접 작업할 수 있도록 설계되었습니다. 즉, 터미널에서의 생성, 스크립팅, 모델 테스트, 그리고 자동화된 파이프라인(pipelines)에 생성 작업을 포함시키는 작업이 가능합니다.

핵심 명령어는 runware run입니다:

runware run runware:101@1 positivePrompt="a chess match in the park" width=1024 height=1024

결과는 ./outputs 폴더로 자동 다운로드됩니다.

동일한 run 명령어를 비디오, 오디오, 3D 및 텍스트 추론(inference)에도 사용할 수 있으며, 모델 식별자(model identifier)만 교체하면 됩니다. CLI는 모델의 스키마를 자동으로 가져오고 작업이 실행되기 전에 파라미터(parameters)를 검증하므로, 비용을 지불하기 전에 실수를 확인할 수 있습니다.

생성 외에도 CLI를 통해 모델 카탈로그를 검색하고, 가격을 확인하며, 모델의 전체 파라미터 스키마를 검사하고, 자주 실행하는 구성에 대한 프리셋(presets)을 관리할 수 있습니다. 출력은 --format json을 지원하여 다른 도구나 스크립트로 파이핑(piping)할 수 있으므로 자동화에 실용적입니다.

모델 검색

runware model search -q "flux"

모델 매개변수 확인 (Check a model's parameters before running)

runware model schema runware:101@1 --format json

API 키를 통한 계정 및 사용량 확인 (Check your account and usage across your API keys)

runware account details --format JSON

MCP Server와 마찬가지로, CLI를 통한 탐색 및 검사 호출은 무료입니다. CLI를 통해 Runware의 서비스를 이용하는 데 추가 비용이 발생하지 않습니다.

CLI 또는 MCP: 어떤 것이 필요할까요?

**MCP 서버(The MCP server)**는 이미 에이전어 내부에서 작업하고 있을 때 적합한 선택지입니다. 사용자가 원하는 것을 설명하면, 에이전트가 도구 호출을 처리하고 대화 내에서 생성이 이루어집니다. 특히 에이전트가 모델 선택을 알아내거나, 여러 모달리티에 걸쳐 체인(chain) 호출을 하거나, 미디어 생성 작업을 더 큰 작업으로 통합해야 할 때 유용합니다.

**CLI(Command Line Interface)**는 에이전트 없이 직접 작업하고 싶을 때 적합한 선택지입니다. MCP와 달리 대화형이 아니므로, 원하는 것을 자연어로 설명하기보다는 어떤 명령어를 실행하고 어떤 매개변수를 전달해야 하는지 알아야 합니다. 이 방식은 작업이 명확하게 정의되어 있을 때 합리적인 절충안이 됩니다: 배치 작업을 스크립팅하거나, CI/CD에서 생성을 실행하거나, 단순히 터미널 창에서 에이전트 세션을 띄우지 않고 빠르게 무언가를 생성할 때 유용합니다.

시작하기 (Getting started)

호스팅 MCP (Hosted MCP) (Claude, Cursor, VS Code 및 대부분의 다른 클라이언트):

클라이언트 설정에서 https://mcp.runware.ai를 커스텀 MCP 서버로 추가하고, 안내에 따라 OAuth 흐름을 완료하세요. Runware 브랜드 페이지에 Runware API 키를 붙여넣게 되는데, 이는 API 키가 노출되는 유일한 시점입니다.

로컬 MCP 서버 (Local MCP server):

npx @runware/mcp

환경 변수에 RUNWARE_API_KEY를 설정하고 클라이언트가 로컬 서버를 가리키도록 설정하세요.

클라이언트별 MCP 설정 정보가 담긴 랜딩 페이지는 runware.ai/mcp에서 확인할 수 있습니다.

CLI:

macOS:

brew tap runware/tap brew install runware

Windows (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

그 다음, 어떤 플랫폼에서든 API 키로 인증하세요:

runware auth login

인증이 완료되면 runware ping을 실행하여 연결을 확인하세요. 이제 준비가 되었습니다.

전체 CLI 레퍼런스는 github.com/Runware/runware-cli에서 확인할 수 있습니다.

클라이언트별 CLI 설정 정보가 담긴 랜딩 페이지는 runware.ai/cli에 있습니다.

FAQ

MCP와 CLI의 차이점은 무엇인가요?
MCP는 대화형(conversational)입니다. 사용자가 원하는 것을 설명하면 에이전트가 모델 선택, 파라미터(parameters), 도구 호출(tool calls)을 처리합니다. CLI는 직접적(direct)입니다. 사용자가 직접 명령어를 작성하며, 이는 스크립팅, 자동화, 그리고 에이전트의 개입을 원하지 않는 상황에 더 적합합니다. 두 방식 모두 동일한 도구와 모델에 대한 접근을 제공합니다.

CLI는 어떤 플랫폼을 지원하나요?
macOS, Windows, Linux를 지원합니다. macOS는 Homebrew를 통해, Windows는 Scoop을 통해, Linux는 셸 설치 프로그램(shell installer)을 통해 설치할 수 있습니다.

소스 코드로 빌드할 수 있나요?
네. 저장소(repo)를 클론(clone)한 후 make build를 실행하세요. 전체 단계는 docs에 설명되어 있습니다.

둘 중 하나를 사용하려면 Runware 계정이 필요한가요?
네, 둘 다 무료 Runware API 키가 필요합니다. runware.ai에서 계정을 생성하고 API 키를 발급받을 수 있습니다.

CLI와 MCP를 모두 사용할 수 있나요?
네. 필요에 따라 동일한 API 키를 공유하여 동일한 계정 잔액과 동일한 모델 카탈로그(model catalog)를 연결할 수도 있고, 서로 다른 키로 설정할 수도 있습니다. 에이전트(agent)와 함께 작업할 때는 MCP를 사용하고, 터미널(terminal)이나 스크립트(script) 환경에서는 CLI를 사용하세요.

WebSocket인가요, REST인가요?
기본적으로는 WebSocket 방식이지만, --transport http 옵션을 사용하여 전환할 수 있습니다.