JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 23
  • Score
    100M100P100Q46724F
  • License MIT

MCP server for Runware AI image and video generation

Package Exports

  • runware-mcp
  • runware-mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (runware-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Runware MCP Server

AI Media Generation for Any MCP Client

22 Tools 6 Resources 9 Providers 100% API Coverage

Turn any MCP-compatible AI assistant into a creative powerhouse.
Images. Videos. Audio. Vectors. All from natural language.

What Is This?

An MCP server that connects your AI coding assistant directly to Runware's AI media generation infrastructure. Works with any client that supports the Model Context Protocol.

View diagrams on GitHub

One config. Zero complexity. Infinite creativity.

Installation

Add the server to your MCP client config:

{
  "mcpServers": {
    "runware": {
      "command": "npx",
      "args": ["-y", "runware-mcp"],
      "env": {
        "RUNWARE_API_KEY": "your-api-key"
      }
    }
  }
}

Config locations by client

Client Config Location
**Claude Code** `~/.claude.json` or project `.mcp.json`
**Claude Desktop (macOS)** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Claude Desktop (Linux)** `~/.config/claude/claude_desktop_config.json`
**Claude Desktop (Windows)** `%APPDATA%\Claude\claude_desktop_config.json`
**Cursor** `.cursor/mcp.json` in your project root
**Codex CLI** `~/.codex/config.toml` or project `.codex/config.toml`
**VS Code (Copilot)** `.vscode/mcp.json` in your project root

Note: Config format may vary slightly by client. Check your client's MCP documentation for exact syntax. Codex CLI uses TOML — see the Codex MCP docs for setup.

That's it. No pip install. No virtual environments. No Python version conflicts. Just paste, restart, create.

Capabilities at a Glance

View diagrams on GitHub

The Complete Toolset

Image Generation & Manipulation

Tool What It Does Key Features
`imageInference` Text/image to images 60+ parameters, LoRA, ControlNet, IP-Adapters
`photoMaker` Preserve identity across generations Face consistency, style transfer
`imageUpscale` Enhance resolution up to 4x Multiple algorithms, preserve details
`imageBackgroundRemoval` Remove backgrounds instantly Alpha matting, custom colors
`imageCaption` Describe images in detail Multiple models, structured output
`imageMasking` Generate segmentation masks Face, body, hands detection
`imageUpload` Upload local images Base64, URL, data URI support
`vectorize` Convert raster to SVG Perfect for logos, icons

Video Generation

Tool What It Does Providers
`videoInference` Create videos from text/images Kling, Veo, MiniMax, PixVerse, Runway, Vidu, Wan, Sync
`listVideoModels` Browse available models All providers with specs
`getVideoModelInfo` Get model details Dimensions, duration, features

Audio Generation

Tool What It Does Features
`audioInference` Generate music, SFX, speech ElevenLabs, Mirelo, 14 voices
`transcription` Video to text transcription Multiple languages

Creative Tools

Tool What It Does Use Cases
`promptEnhance` Supercharge your prompts 1-5 variations, AI enrichment
`controlNetPreprocess` Prepare images for ControlNet 12 preprocessors
`styleTransfer` Apply artistic styles Combine with any model

Utilities

Tool What It Does Why It Matters
`modelSearch` Search 100,000+ models Find the perfect model
`costEstimate` Estimate before generating Budget control
`getAccountBalance` Check your credits Never run dry

Batch Operations

Tool What It Does Power Features
`processFolder` Process entire folders Upscale, remove BG, caption, vectorize
`batchImageInference` Generate from multiple prompts Concurrent processing
`watchFolder` Auto-process new files Pipelines, debouncing

Provider-Specific Features

This server exposes the full capabilities of each provider:

Provider Exclusive Features
**Alibaba (Wan)** Prompt extension, multi-shot videos, audio generation
**Black Forest Labs** Safety tolerance, raw mode, prompt upsampling
**Bria** Content moderation, medium selection, fast mode
**Ideogram** 65+ style types, color palettes, magic prompt
**ByteDance** Sequential image narratives (1-15 images)
**KlingAI** Sound generation, camera fixed mode
**PixVerse** 20 viral effects, 21 camera movements, multi-clip
**Google Veo** Prompt enhancement, audio generation (Veo 3)
**Sync.so** Lip sync, speaker detection, audio segments

MCP Resources

Access your generated content programmatically:

Resource URI Description
`runware://images/{id}` Generated images with metadata
`runware://videos/{id}` Generated videos with metadata
`runware://audio/{id}` Generated audio with metadata
`runware://session/history` Full session generation history
`runware://analytics/{period}` Usage analytics (day/week/month/all)

Prompt Templates

Pre-built workflows for common tasks:

Template Perfect For
`product-photo` E-commerce, catalogs, marketing
`avatar-generator` Profile pictures, characters
`video-scene` Storyboarding, content creation
`style-transfer` Artistic transformations
`ui-mockup` Web/mobile design prototypes
`thumbnail` YouTube, articles, social media
`music-composition` Background music, jingles

Documentation

This MCP server includes comprehensive built-in documentation accessible as MCP resources. Any connected client can discover and read detailed API references, feature guides, and provider docs on demand.

42 documentation resources organized across 5 categories:

Category Count What's Covered
**Concepts** 5 AIR identifiers, task responses, output types, async delivery, connection
**Tools** 13 Full parameter reference for every tool
**Features** 10 ControlNet, LoRA, IP-Adapters, prompt weighting, acceleration, and more
**Providers** 9 Provider-specific settings and capabilities
**Guides** 5 Batch processing, cost optimization, quality tuning, combining features

Example URIs: runware://docs/tools/image-inference, runware://docs/features/controlnet-guide, runware://docs/providers/kling-ai, runware://docs/guides/cost-optimization

Ask your AI assistant to list or read any runware://docs/* resource for detailed reference information.

Architecture

View diagrams on GitHub

What's Included

A ground-up TypeScript rewrite covering 100% of the Runware API.

Feature Details
**API Coverage** 100% — every endpoint, every parameter
**Tools** 22 tools across image, video, audio, and batch ops
**Providers** 9 providers with full provider-specific settings
**Type Safety** Strict TypeScript + Zod validation on every input
**Security** SSRF protection, rate limiting, path traversal prevention
**Testing** 80%+ coverage across 1300+ tests
**Install** `npx runware-mcp` — zero setup

Video Model Comparison

Provider Models Max Resolution Max Duration Special Features
**KlingAI** 10 1920x1080 10s Sound, camera lock
**Google Veo** 3 1920x1080 8s Audio gen (Veo 3)
**MiniMax** 4 1920x1080 5s Fast generation
**PixVerse** 3 1280x720 4s Viral effects
**Vidu** 4 1280x720 4s Reference videos
**Wan/Alibaba** 2 1280x720 5s Multi-shot
**Runway** 2 1920x1080 10s Professional
**Sync.so** 1 1920x1080 60s Lip sync

ControlNet Preprocessors

Preprocessor Use Case Best For
`canny` Edge detection Architectural, product
`depth` Depth mapping Scenes, landscapes
`mlsd` Line segments Interior design
`normalbae` Normal maps 3D-like rendering
`openpose` Human pose Character art
`tile` Tile processing Textures, patterns
`seg` Segmentation Complex scenes
`lineart` Line extraction Illustrations
`lineart_anime` Anime lines Anime, manga
`shuffle` Content shuffle Abstract, creative
`scribble` Scribble style Concept art
`softedge` Soft edges Soft, dreamy

Configuration Reference

Variable Default Description
`RUNWARE_API_KEY` **required** Your Runware API key
`NODE_ENV` `production` Environment mode
`LOG_LEVEL` `info` Logging verbosity
`MAX_FILE_SIZE_MB` `50` Max upload size
`REQUEST_TIMEOUT_MS` `60000` API timeout
`POLL_MAX_ATTEMPTS` `150` Video poll attempts
`RATE_LIMIT_MAX_TOKENS` `10` Rate limit burst
`RATE_LIMIT_REFILL_RATE` `1` Tokens per second
`WATCH_FOLDERS` — Auto-watch folders
`WATCH_DEBOUNCE_MS` `500` Watch debounce

Security

Protection Implementation
**Input Validation** Zod schemas on every tool
**Path Traversal** Canonicalization + symlink resolution
**SSRF Protection** Private IP + metadata endpoint blocking
**Rate Limiting** Token bucket algorithm
**Error Sanitization** No stack traces or paths leaked

Example Workflows

Product Photography Pipeline

You: "Process all images in /photos/products - remove backgrounds,
      upscale 2x, and save as PNGs to /photos/processed"
Assistant uses processFolder with removeBackground and upscale pipeline

Video Storyboard

You: "Create a 3-part video story: sunrise over mountains,
      eagle soaring, landing on a branch. Use Kling, 5s each."

Assistant generates 3 coordinated videos with consistent style

Brand Asset Generation

You: "Generate 5 logo variations for 'TechFlow' - modern, minimal,
      tech-focused. Then vectorize the best one."

Assistant uses imageInference, selects best, then vectorize to SVG

Music + Video

You: "Create a 30-second promo video with matching background music"

Assistant uses videoInference + audioInference in parallel

Development

git clone https://github.com/runware/mcp-server
cd mcp-server
npm install
npm run build
npm test
Command Purpose
`npm run build` Compile TypeScript
`npm run dev` Watch mode
`npm run typecheck` Type checking
`npm run lint` Lint with strict rules
`npm run test` Run tests
`npm run test:coverage` Coverage report

Contributing

See CONTRIBUTING.md for the full development guide including project structure, how to add new tools, testing patterns, and code style.

  1. Fork it
  2. Create a feature branch
  3. Make it pass: npm run build && npm run lint && npm test
  4. Submit PR

For version history and release notes, see CHANGELOG.md.

License

MIT

Built for creators who demand more from their AI tools.

22 tools. 9 providers. 100% API coverage. Zero complexity.