io.github.charlesrapp/pruna

🎨 pruna-mcp-server

MCP server for Pruna AI — ultra-fast image generation, editing, upscaling, and video generation directly from your AI assistant.

Pruna AI is an inference API specialized in image and video generation. It offers sub-2-second image generation starting at $0.005/image, with models for text-to-image, image editing, upscaling, and video generation. This MCP server wraps their API so any MCP-compatible client (Claude Desktop, Kiro, Cursor) can generate visual content natively.

Conforms to MCP Specification 2025-11-25.

Features

• 8 MCP Tools: generate_image, edit_image, try_on_image, upscale_image, generate_video, transform_video, list_models, upload_file
• 7 MCP Prompts: Product photos, virtual staging, social media visuals, game concept art, ad creatives, video ads, image enhancement
• 2 MCP Resources: pruna://models catalog for model discovery without tool calls
• 21 models: 10 text-to-image, 3 editing, 1 virtual try-on, 1 upscale, 4 video, 2 video-to-video
• Smart sync/async: Sync for fast image models, async with polling for video
• Transparent file handling: Pass local paths or URLs — auto-upload handled
• Native MCP image return: ImageContent blocks for clients that support inline display
• Full MCP compliance: Tool annotations, structured content, progress notifications

Quick Start

# With uvx (zero install)
uvx pruna-mcp-server

# Or with pip
pip install pruna-mcp-server
pruna-mcp

Set your API key — get one at pruna.ai (go to the developer portal or contact Pruna to request access):

# macOS Keychain (recommended)
security add-generic-password -a $USER -s PRUNA_API_KEY -w "your-api-key"

# Linux (GNOME Keyring)
secret-tool store --label="Pruna API Key" service pruna-mcp-server key api_key <<< "your-api-key"

# Windows (PowerShell)
[System.Environment]::SetEnvironmentVariable("PRUNA_API_KEY", "your-api-key", "User")

# Or environment variable (all platforms)
export PRUNA_API_KEY="your-api-key"

MCP Client Configuration

Kiro CLI

Add to your agent config (e.g. ~/.kiro/agents/default.json):

In mcpServers:

"pruna": {
  "command": "sh",
  "args": ["-c", "PRUNA_API_KEY=$(security find-generic-password -a $USER -s PRUNA_API_KEY -w) uv run --directory /path/to/pruna-mcp-server pruna-mcp"],
  "autoApprove": ["generate_image", "edit_image", "try_on_image", "upscale_image", "generate_video", "transform_video", "list_models", "upload_file"]
}

In tools, add: "@pruna/*"

In allowedTools, add: "generate_image", "edit_image", "try_on_image", "upscale_image", "generate_video", "transform_video", "list_models", "upload_file"

Note: Kiro agents use a tools whitelist with @server-name/* syntax and an allowedTools list. Both must include the Pruna tools for them to be available.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "pruna": {
      "command": "sh",
      "args": ["-c", "PRUNA_API_KEY=$(security find-generic-password -a $USER -s PRUNA_API_KEY -w) /path/to/uv run --directory /path/to/pruna-mcp-server pruna-mcp"]
    }
  }
}

Important: Use the full path to uv (e.g. /Users/you/.local/bin/uv) — Claude Desktop launches processes with a minimal PATH that doesn't include ~/.local/bin.

Note: Claude Desktop does not render ImageContent inline in the chat. The image is generated and saved locally — Claude will reference the file path in its response.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "pruna": {
      "command": "uvx",
      "args": ["pruna-mcp-server"],
      "env": { "PRUNA_API_KEY": "your-api-key" }
    }
  }
}

Tools

Tool	Description	Pricing
generate_image	Text-to-image with 10 models	From $0.0001/image
edit_image	Edit 1-5 images with text instructions	From $0.010/image
try_on_image	Virtual try-on: fit up to 11 garments onto a person	$0.015 first + $0.008/extra garment
upscale_image	AI upscaling up to 128 megapixels	From $0.005/image
generate_video	Text/image/audio to video	From $0.005/s
transform_video	Video-to-video: animate a subject or replace characters	$0.03/s (720p), $0.06/s (1080p)
list_models	Browse all available models with pricing	Free
upload_file	Upload files for editing/video workflows	Free

Image tools return both a JSON metadata block and a native MCP ImageContent block (base64, for images < 5MB).

Video tools return a JSON metadata block (including a download_url to the Pruna delivery URL), the .mp4 as a native MCP binary resource (EmbeddedResource blob, for videos < 25MB) so clients materialize the file the same way they save images, and a ResourceLink to the same delivery URL as a fallback for larger files. All tools return an absolute file_path.

Prompts

Built-in workflow templates for common use cases:

Prompt	Use Case	Example
product-photo	E-commerce product shots	"white leather sneakers on clean background"
virtual-staging	Real estate room staging	Stage empty rooms with furniture
social-media-visual	Platform-optimized visuals	Auto aspect ratio per platform
game-concept-art	Game assets & environments	Characters, weapons, landscapes
ad-creative	Digital ads with text overlay	Headlines rendered in the image
video-ad	Short video ads	Talking heads, product demos
image-enhance	Upscale + enhance workflow	AI-generated image refinement

Configuration

Environment Variable	Required	Default	Description
PRUNA_API_KEY	✅	—	Your Pruna AI API key
PRUNA_OUTPUT_DIR	—	~/pruna-output	Directory for downloaded files
PRUNA_POLL_INTERVAL	—	2	Seconds between async polls
PRUNA_TIMEOUT	—	120	HTTP timeout in seconds
PRUNA_MAX_RETRIES	—	3	Max retries on transient errors

Client Compatibility

Client	Transport	Status	Notes
Kiro CLI	STDIO	✅ Tested	Requires tools + allowedTools config
Claude Desktop	STDIO	✅ Tested	Use full path to uv; no inline image display
Cursor	STDIO	🔲 Planned	—
Claude Code	STDIO	🔲 Planned	—

Development

git clone https://github.com/charlesrapp/pruna-mcp-server.git
cd pruna-mcp-server
uv sync --extra dev

# Run tests (147 tests, 97% coverage)
uv run pytest --cov

# Lint & type check
uv run ruff check src/ tests/
uv run mypy src/

See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE.