# Runware MCP Server
A powerful Model Context Protocol (MCP) server that provides lightning fast image and video generation tools using the [Runware API](https://runware.ai). 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 parameters
- **`photoMaker`**: Subject personalization with PhotoMaker technology
- **`imageUpscale`**: High-quality image resolution enhancement
- **`imageBackgroundRemoval`**: Background removal with multiple AI models
- **`imageCaption`**: AI-powered image description generation
- **`imageMasking`**: Automatic mask generation for faces, hands, and people
### **Video Generation Tools**
- **`videoInference`**: Text-to-video and image-to-video generation
- **`listVideoModels`**: Discover available video models
- **`getVideoModelInfo`**: Get detailed model specifications
### **Utility Tools**
- **`imageUpload`**: Upload local images to get Runware UUIDs
- **`modelSearch`**: Search and discover AI models on the platform
### **Smart Features**
- **Automatic Model Selection**: I2V uses `klingai:5@2`, T2V uses `google: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](https://github.com/jlowin/fastmcp) with [Starlette](https://www.starlette.io/) web framework
- **Server**: [Uvicorn](https://www.uvicorn.org/) ASGI server
- **API**: Direct integration with [Runware's AI services](https://runware.ai)
## Prerequisites
- **Python**: 3.10 or higher
- **Runware API Key**: Get your API key from [Runware Dashboard](https://my.runware.ai)
- **Dependencies**: See `requirements.txt` or `pyproject.toml`
## Installation
### **1. Clone the Repository**
```bash
git clone https://github.com/Runware/MCP-Runware.git
cd MCP-Runware
```
### **2. Install Dependencies**
```bash
# 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:
```bash
RUNWARE_API_KEY=your_api_key_here
```
## Deployment Methods
### **Method 1: SSE Server (Recommended for Production)**
#### **Docker Deployment**
```bash
# 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**
```bash
# 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](https://my.runware.ai/models/all)
## 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](https://claude.ai/public/artifacts/0f28d79d-47bd-4fb8-bc25-e2699d78479f)
- 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](https://runware.ai/docs)
- **Models**: [Browse All Models](https://my.runware.ai/models/all)
- **Dashboard**: [Runware Dashboard](https://my.runware.ai)
- **Issues**: Create an issue in this repository
- **Email**: support@runware.ai