Runware MCP Server
A powerful Model Context Protocol (MCP) server that provides lightning fast image and video generation tools using the Runware API. This server supports both SSE (Server-Sent Events) transport for custom claude connector and direct claude desktop installation as well.
Features
Image Generation Tools
imageInference: Full-featured image generation with advanced parametersphotoMaker: Subject personalization with PhotoMaker technologyimageUpscale: High-quality image resolution enhancementimageBackgroundRemoval: Background removal with multiple AI modelsimageCaption: AI-powered image description generationimageMasking: Automatic mask generation for faces, hands, and people
Video Generation Tools
videoInference: Text-to-video and image-to-video generationlistVideoModels: Discover available video modelsgetVideoModelInfo: Get detailed model specifications
Utility Tools
imageUpload: Upload local images to get Runware UUIDsmodelSearch: Search and discover AI models on the platform
Smart Features
- Automatic Model Selection: I2V uses
klingai:5@2, T2V usesgoogle:3@1 - Input Validation: Prevents Claude upload URL pasting and validates dimensions
- Comprehensive Error Handling: Clear error messages and guidance
Demo
Watch the demo video to see the Runware MCP server in action:
https://github.com/user-attachments/assets/9732096b-8513-455c-9759-cc88363c42f9
Architecture
[ MCP Client / AI Assistant ]
|
(connects via SSE over HTTP)
|
[ Uvicorn Server ]
|
[ Starlette App ]
|
[ FastMCP Server ]
|
[ Runware API ]
- Transport: SSE (Server-Sent Events) for real-time communication
- Framework: FastMCP with Starlette web framework
- Server: Uvicorn ASGI server
- API: Direct integration with Runware's AI services
Prerequisites
- Python: 3.10 or higher
- Runware API Key: Get your API key from Runware Dashboard
- Dependencies: See
requirements.txtorpyproject.toml
Installation
1. Clone the Repository
git clone https://github.com/Runware/MCP-Runware.git
cd MCP-Runware
2. Install Dependencies
# Using uv (recommended)
uv venv
source .venv/bin/activate
uv pip install .
# Or using pip
pip install -r requirements.txt
3. Environment Setup
Create a .env file in the project root:
RUNWARE_API_KEY=your_api_key_here
Deployment Methods
Method 1: SSE Server (Recommended for Production)
Docker Deployment
# Build the Docker image
docker build -t runware_mcp_sse .
# Run the container
docker run --rm -p 8081:8081 runware_mcp_sse
Method 2: MCP Install (Direct Integration)
Install in Claude Desktop
# From the project directory
mcp install --with-editable . runware_mcp_server.py
Model Recommendations
Image Generation
- Default:
civitai:943001@1055701(SDXL-based) - PhotoMaker:
civitai:139562@344487(RealVisXL V4.0) - Background Removal:
runware:109@1(RemBG 1.4)
Video Generation
- Image-to-Video (I2V):
klingai:5@2(1920x1080) - Text-to-Video (T2V):
google:3@1(1280x720)
You can find all additional models here: Runware Models
Configuration
Environment Variables
RUNWARE_API_KEY: Your Runware API key (required)
Input Validation
- Rejects Claude upload URLs (
https://files.*). Claude tends to include base64 strings in its reasoning/thinking process, which rapidly fills the context window with garbage data. Learn more about this issue - Supports local file paths, public accessible URLs (make sure it has proper file extension such as JPG, PNG, WEBP, etc), and Runware UUIDs
Support
- Documentation: Runware API Docs
- Models: Browse All Models
- Dashboard: Runware Dashboard
- Issues: Create an issue in this repository
- Email: support@runware.ai