Skip to main content
Glama
Sign In
deeneskoruzh
pruna-mcp-server

pruna-mcp-server

by charlesrapp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

🎨 pruna-mcp-server

CI PyPI Python License: MIT

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

Related MCP server: jgkme/kilo-image-gen-mcp

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.

Available Tools

8 tools
edit_imageA

Edit one or more images with text instructions using Pruna AI.

Args: prompt: Edit instruction describing the desired changes images: 1-5 image URLs or local file paths model: Model to use (default: p-image-edit) aspect_ratio: Output aspect ratio seed: Random seed for reproducible generation

Inputs: images (required), prompt (required), seed, model, +1 more.

generate_imageA

Generate an image from a text prompt using Pruna AI.

Args: prompt: Text description of the image to generate model: Model to use (default: p-image) aspect_ratio: Output aspect ratio (1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, custom) width: Custom width 256-1440, multiple of 16. Only when aspect_ratio=custom height: Custom height 256-1440, multiple of 16. Only when aspect_ratio=custom seed: Random seed for reproducible generation

Inputs: prompt (required), seed, model, width, +2 more.

generate_videoB

Generate a video from text, image, or audio using Pruna AI.

Args: prompt: Text prompt for video generation model: Model to use (p-video, wan-t2v, wan-i2v, vace) image: Input image URL/path for image-to-video audio: Input audio URL/path for audio-conditioned video duration: Duration in seconds (1-20) resolution: Video resolution (720p or 1080p) aspect_ratio: Aspect ratio (ignored when image is provided) fps: Frames per second (24 or 48) seed: Random seed for reproducible generation

Inputs: prompt (required), fps, seed, audio, +5 more. Returns: result

list_modelsA
Read-onlyIdempotent

List available Pruna AI models with capabilities and pricing.

Args: category: Filter by category: image, editing, try-on, upscale, video, video-edit

Inputs: category. Returns: result

transform_videoA

Transform a source video using reference images (video-to-video).

Two models are available:

  • p-video-animate: animate a single subject reference image using the motion from the source video (provide exactly 1 reference).

  • p-video-replace: replace the character(s) in the source video using 1-3 identity reference images.

Motion, timing, camera movement, and scene structure are preserved.

Args: video: Source video URL or local file path (.mp4) references: Reference images (URLs or local file paths). Exactly 1 for p-video-animate, 1-3 for p-video-replace. model: Model to use (p-video-animate or p-video-replace) resolution: Output resolution (720p or 1080p) target_fps: Working FPS (original, 24, or 48) instruction_prompt: Optional guidance on how to apply the transform turbo: Faster generation for slightly lower quality save_audio: Save the output video with audio ignore_audio: Ignore source audio during generation seed: Random seed for reproducible generation

Inputs: video (required), references (required), seed, model, +6 more. Returns: result

try_on_imageA

Virtually fit one or more garments onto a person's photo using Pruna AI.

Args: person_image: Image URL or local file path of the person garment_images: 1-11 garment reference images (URLs or local file paths). Up to 6 recommended for best quality. model: Model to use (default: p-image-try-on) prompt: Experimental guidance for non-flatlay garment images (e.g. which garment from which image to use) turbo: Faster generation. Not recommended for more than 4 garments reference_pose: Experimental. Image URL/path to repose the person before try-on seed: Random seed for reproducible generation output_format: Output format (webp, jpg, png) output_quality: Quality for jpg/webp outputs (0-100) preserve_input_size: Resize the result back to the person image size

Inputs: person_image (required), garment_images (required), seed, model, +6 more.

upload_fileA
Idempotent

Upload a local file to Pruna AI for use in editing/video workflows.

Args: file_path: Local file path to upload (max 20MB)

Inputs: file_path (required). Returns: result

upscale_imageA
Idempotent

Upscale an image using Pruna AI.

Args: image: Image URL or local file path to upscale target: Target resolution in megapixels (1-128, capped at 128 MP) output_format: Output format (webp, jpg, png) enhance_details: Enhance fine textures enhance_realism: Improve realism (recommended for AI-generated images)

Inputs: image (required), target, output_format, enhance_details, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.1/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: image generation, image editing, video generation, video transformation, try-on, upscaling, model listing, and file upload. No two tools overlap in function.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., generate_image, edit_image, list_models) using snake_case, making them predictable and easy to understand.

    Tool Count5/5

    With 8 tools, the server is well-scoped for its purpose—covering core media generation and editing tasks without being overly sparse or cluttered.

    Completeness4/5

    The set covers major operations: generation, editing, transformation, upscaling, try-on, model listing, and file upload. A minor gap is the lack of a text-based video editing tool analogous to edit_image, but overall it's quite complete.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers